From 5f8448ef6b85a9ff72c5af4cec99183c8bb60dc6 Mon Sep 17 00:00:00 2001 From: marha Date: Tue, 10 Apr 2012 14:58:33 +0200 Subject: Updated following packages: bigreqsproto-1.1.2 fontsproto-2.1.2 recordproto-1.14.2 scrnsaverproto-1.2.2 xcmiscproto-1.2.2 libXt-1.1.3 xhost-1.0.5 kbproto-1.0.6 libXrender-0.9.7 libxkbfile-1.0.8 freetype-2.4.9 libXaw-1.0.10 libXpm-3.5.10 xproto-7.0.23 --- libXt/specs/appC.xml | 1970 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1970 insertions(+) create mode 100644 libXt/specs/appC.xml (limited to 'libXt/specs/appC.xml') diff --git a/libXt/specs/appC.xml b/libXt/specs/appC.xml new file mode 100644 index 000000000..4598ac99e --- /dev/null +++ b/libXt/specs/appC.xml @@ -0,0 +1,1970 @@ + +Compatibility Functions +<footnote> +<para> +This appendix is part of the formal Intrinsics Specification. +</para> +</footnote> + + +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 + 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 + +function calls + +followed by +, +then calls + +with display_string NULL and +application_name NULL, and finally calls + +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 + +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 + 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 + +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 + 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. + + + + + + + +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 + + + + + + +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 + 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 + +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 + 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 + +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 + 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. + + + + + + + +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 + 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. + + + + + + + +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 + 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 + +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 + + + + + +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 + + + + + +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 + 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 + +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 + 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 +. + + + +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 + 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 +. + + + +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 + String 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 + String 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 +. + + -- cgit v1.2.3