# 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 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 and 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 on their child within their insert_child procedure. Creators of pop-up children need to call themselves.

and have been replaced by and .

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 or .

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 function calls followed by , then calls with display_string NULL and application_name NULL, and finally calls 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 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 terminates the application. If fallback_resources is non-NULL, is called with the value prior to calling .

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 procedure is identical in function to 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: , , , , , , , , , , , , and .

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.

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

void `XtMainLoop` void

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

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, 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 . must be called before using this routine.

void `XtProcessEvent` XtInputMask mask

mask

  Specifies the type of input to process.

processes one X event, timeout, or alternate input source (depending on the value of mask), blocking if necessary. It has been replaced by . 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, fills in the event and returns a nonzero value. If no X input is on the queue, flushes the output buffer and blocks until input is available, possibly calling some timeout callbacks in the process. If the input is an event, fills in the event and returns a nonzero value. Otherwise, the input is for an alternate input source, and returns zero. This routine has been replaced by . must be called before using this routine.

Boolean `XtPending` void

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 . 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 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.) 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 . 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 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 . 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 . 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 calls with application_name NULL, the application class passed to , and the default application context created by . This routine has been replaced by .

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

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 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 has been replaced by .

The 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 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 .

To register an old-format converter, use or .

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.

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

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.

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

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

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 function looks up the type converter registered to convert from_type to to_type, computes any additional arguments needed, and then calls or . The 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, 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 must be copied immediately by the caller, as it may point to static data in the type converter.

has been replaced by , and has been superseded by .

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

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 sharable 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 had only a gc argument. Therefore, this function is not very portable, and you are encouraged to use instead.

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

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 and as part of X Toolkit initialization. This routine has been replaced by . must be called before using this routine.

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

void `XtSetSelectionTimeout` unsigned long timeout

timeout

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

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

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 . 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 .

XrmDatabase *`XtGetErrorDatabase` void

The 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 .

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

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 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 .

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

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 . Fatal error message handlers should not return. If one does, subsequent Intrinsics behavior is undefined. This routine has been superseded by .

To call the high-level error handler, use .

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 .

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

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 . This routine has been superseded by .

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

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 .

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

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 .

To call the installed fatal error procedure, use .

void `XtError` const char * message

message

  Specifies the message to be reported.

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

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

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 .

To call the installed nonfatal error procedure, use .

void `XtWarning` const char * message

message

  Specifies the nonfatal error message to be reported.

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