Appendix C. Compatibility Functions ^[1]

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, String application_class, XrmOptionDescList options, Cardinal num_options, int *argc_in_out, String *argv_in_out, String *fallback_resources, ArgList args, Cardinal num_args);

Widget XtAppInitialize(XtAppContext *app_context_return, String application_class, XrmOptionDescList options, Cardinal num_options, int *argc_in_out, String *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 application\%Shell\%Widget\%Class, 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, String application_class, XrmOptionDescList options, Cardinal num_options, int *argc_in_out, String *argv_in_out, String *fallback_resources);

Widget XtVaAppInitialize(XtAppContext *app_context_return, String application_class, XrmOptionDescList options, Cardinal num_options, int *argc_in_out, String *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(String shell_name, String application_class, XrmOptionDescRec options, Cardinal num_options, int *argc, String argv);

Widget XtInitialize(String shell_name, String application_class, XrmOptionDescRec options, Cardinal num_options, int *argc, String 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);

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);

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);

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);

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();

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);

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);

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(String 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);

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(String src);

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(String from_type, String 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, String from_type, String 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, String from_type, XrmValuePtr from, String 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);

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 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);

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();

unsigned long XtGetSelectionTimeout();

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();

XrmDatabase *XtGetErrorDatabase();

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 XtGetErrorDatbaseText. 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(String name, String default, String 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(String name, String type, String class, String default, String *params, Cardinal *num_params);

void XtErrorMsg(String name, String type, String class, String 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(String name, String type, String class, String default, String *params, Cardinal *num_params);

void XtWarningMsg(String name, String type, String class, String 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(String message);

void XtError(String 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(String message);

void XtWarning(String 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.

^[1] This appendix is part of the formal Intrinsics Specification.

Appendix C. Compatibility Functions [1]

Appendix C. Compatibility Functions ^[1]