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