specs/appC

   1 .\" $Xorg: appC,v 1.3 2000/08/17 19:42:48 cpqbld Exp $
   2 .\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
   3 .\" X Consortium
   4 .\"
   5 .\" Permission is hereby granted, free of charge, to any person obtaining
   6 .\" a copy of this software and associated documentation files (the
   7 .\" "Software"), to deal in the Software without restriction, including
   8 .\" without limitation the rights to use, copy, modify, merge, publish,
   9 .\" distribute, sublicense, and/or sell copies of the Software, and to
  10 .\" permit persons to whom the Software is furnished to do so, subject to
  11 .\" the following conditions:
  12 .\"
  13 .\" The above copyright notice and this permission notice shall be included
  14 .\" in all copies or substantial portions of the Software.
  15 .\"
  16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  19 .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
  20 .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  21 .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  22 .\" OTHER DEALINGS IN THE SOFTWARE.
  23 .\"
  24 .\" Except as contained in this notice, the name of the X Consortium shall
  25 .\" not be used in advertising or otherwise to promote the sale, use or
  26 .\" other dealings in this Software without prior written authorization
  27 .\" from the X Consortium.
  28 .\"
  29 .\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
  30 .\" Digital Equipment Corporation, Maynard, Massachusetts.
  31 .\"
  32 .\" Permission to use, copy, modify and distribute this documentation for any
  33 .\" purpose and without fee is hereby granted, provided that the above copyright
  34 .\" notice appears in all copies and that both that copyright notice and this
  35 .\" permission notice appear in supporting documentation, and that the name of
  36 .\" Digital not be used in in advertising or publicity pertaining
  37 .\" to distribution of the software without specific, written prior permission.
  38 .\" Digital makes no representations about the suitability of the
  39 .\" software described herein for any purpose.
  40 .\" It is provided ``as is'' without express or implied warranty.
  41 .\"
  42 .bp
  43 \&
  44 .sp 1
  45 .ce 3
  46 \s+1\fBAppendix C\fP\s-1
  47
  48 \s+1\fBCompatibility Functions\fP\s-1
  49 .sp 2
  50 .LP
  51 .XS
  52 \fBAppendix C \(em Compatibility Functions\fP
  53 .XE
  54 .FS
  55 This appendix is part of the formal Intrinsics Specification.
  56 .FE
  57 .LP
  58 In prototype versions of the \*(tk
  59 each widget class
  60 implemented an Xt<\^\fIWidget\fP\^>Create (for example,
  61 .PN XtLabelCreate )
  62 function, in which most of the code was identical from widget to widget.
  63 In the \*(xI, a single generic
  64 .PN XtCreateWidget
  65 performs most of the common work and then calls the initialize procedure
  66 implemented for the particular widget class.
  67 .LP
  68 Each Composite class also implemented the procedures
  69 Xt<\^\fIWidget\fP\^>Add and an Xt<\^\fIWidget\fP\^>Delete (for example,
  70 .PN XtButtonBoxAddButton
  71 and
  72 .PN XtButtonBoxDeleteButton ).
  73 In the \*(xI, the Composite generic procedures
  74 .PN XtManageChildren
  75 and
  76 .PN XtUnmanageChildren
  77 perform error checking and screening out of certain children.
  78 Then they call the change_managed procedure
  79 implemented for the widget's Composite class.
  80 If the widget's parent has not yet been realized,
  81 the call to the change_managed procedure is delayed until realization time.
  82 .LP
  83 Old-style calls can be implemented in the \*(tk by defining
  84 one-line procedures or macros that invoke a generic routine.  For example,
  85 you could define the macro
  86 .PN XtLabelCreate
  87 as:
  88 .IP
  89 .Ds 0
  90 .TA .5i 3i
  91 .ta .5i 3i
  92 #define XtLabelCreate(\fIname\fP, \fIparent\fP, \fIargs\fP, \fInum_args\fP) \\
  93         ((LabelWidget) XtCreateWidget(\fIname\fP, \fIlabelWidgetClass\fP,   \
  94 \fIparent\fP, \fIargs\fP, \fInum_args\fP))
  95 .De
  96 .sp
  97 .LP
  98 Pop-up shells in some of the prototypes automatically performed an
  99 .PN XtManageChild
 100 on their child within their insert_child procedure.
 101 .IN "insert_child procedure"
 102 Creators of pop-up children need to call
 103 .PN XtManageChild
 104 themselves.
 105 .sp
 106 .LP
 107 .PN XtAppInitialize
 108 and
 109 .PN XtVaAppInitialize
 110 have been replaced by
 111 .PN XtOpenApplication
 112 and
 113 .PN XtVaOpenApplication .
 114 .LP
 115 To initialize the \*(xI internals, create an application context,
 116 open and initialize a display, and create the initial application shell
 117 instance, an application may use
 118 .PN XtAppInitialize
 119 or
 120 .PN XtVaAppInitialize .
 121 .LP
 122 .IN "XtAppInitialize" "" "@DEF@"
 123 .sM
 124 .FD 0
 125 Widget XtAppInitialize(\fIapp_context_return\fP, \fIapplication_class\fP, \
 126 \fIoptions\fP, \fInum_options\fP,
 127 .br
 128                        \fIargc_in_out\fP, \fIargv_in_out\fP, \
 129 \fIfallback_resources\fP, \fIargs\fP, \fInum_args\fP)
 130 .br
 131       XtAppContext *\fIapp_context_return\fP;
 132 .br
 133       String \fIapplication_class\fP;
 134 .br
 135       XrmOptionDescList \fIoptions\fP;
 136 .br
 137       Cardinal \fInum_options\fP;
 138 .br
 139       int *\fIargc_in_out\fP;
 140 .br
 141       String *\fIargv_in_out\fP;
 142 .br
 143       String *\fIfallback_resources\fP;
 144 .br
 145       ArgList \fIargs\fP;
 146 .br
 147       Cardinal \fInum_args\fP;
 148 .FN
 149 .IP \fIapp_context_return\fP 1.5i
 150 Returns the application context, if non-NULL.
 151 .IP \fIapplication_class\fP 1.5i
 152 Specifies the class name of the application.
 153 .IP \fIoptions\fP 1.5i
 154 Specifies the command line options table.
 155 .IP \fInum_options\fP 1.5i
 156 Specifies the number of entries in \fIoptions\fP.
 157 .IP \fIargc_in_out\fP 1.5i
 158 Specifies a pointer to the number of command line arguments.
 159 .IP \fIargv_in_out\fP 1.5i
 160 Specifies a pointer to the command line arguments.
 161 .IP \fIfallback_resources\fP 1.5i
 162 Specifies resource values to be used if the application class resource
 163 file cannot be opened or read, or NULL.
 164 .IP \fIargs\fP 1.5i
 165 Specifies the argument list to override any
 166 other resource specifications for the created shell widget.
 167 .IP \fInum_args\fP 1.5i
 168 Specifies the number of entries in the argument list.
 169 .LP
 170 .eM
 171 The
 172 .PN XtAppInitialize
 173 function calls
 174 .PN XtToolkitInitialize
 175 followed by
 176 .PN XtCreateApplicationContext ,
 177 then calls
 178 .PN XtOpenDisplay
 179 with \fIdisplay_string\fP NULL and
 180 \fIapplication_name\fP NULL, and finally calls
 181 .PN XtAppCreateShell
 182 with \fIapplication_name\fP NULL, \fIwidget_class\fP
 183 .PN application\%Shell\%Widget\%Class ,
 184 and the specified \fIargs\fP and \fInum_args\fP
 185 and returns the created shell.  The modified \fIargc\fP and \fIargv\fP returned by
 186 .PN XtDisplayInitialize
 187 are returned in \fIargc_in_out\fP and \fIargv_in_out\fP.  If
 188 \fIapp_context_return\fP is not NULL, the created application context is
 189 also returned.  If the display specified by the command line cannot be
 190 opened, an error message is issued and
 191 .PN XtAppInitialize
 192 terminates the application.  If \fIfallback_resources\fP is non-NULL,
 193 .PN XtAppSetFallbackResources
 194 is called with the value prior to calling
 195 .PN XtOpenDisplay .
 196 .sp
 197 .LP
 198 .IN "XtVaAppInitialize" "" "@DEF@"
 199 .sM
 200 .FD 0
 201 Widget XtVaAppInitialize(\fIapp_context_return\fP, \fIapplication_class\fP, \
 202 \fIoptions\fP, \fInum_options\fP,
 203 .br
 204                          \fIargc_in_out\fP, \fIargv_in_out\fP, \
 205 \fIfallback_resources\fP, ...)
 206 .br
 207     XtAppContext *\fIapp_context_return\fP;
 208 .br
 209     String \fIapplication_class\fP;
 210 .br
 211     XrmOptionDescList \fIoptions\fP;
 212 .br
 213     Cardinal \fInum_options\fP;
 214 .br
 215     int *\fIargc_in_out\fP;
 216 .br
 217     String *\fIargv_in_out\fP;
 218 .br
 219     String *\fIfallback_resources\fP;
 220 .FN
 221 .IP \fIapp_context_return\fP 1.5i
 222 Returns the application context, if non-NULL.
 223 .IP \fIapplication_class\fP 1.5i
 224 Specifies the class name of the application.
 225 .IP \fIoptions\fP 1.5i
 226 Specifies the command line options table.
 227 .IP \fInum_options\fP 1.5i
 228 Specifies the number of entries in \fIoptions\fP.
 229 .IP \fIargc_in_out\fP 1.5i
 230 Specifies a pointer to the number of command line arguments.
 231 .IP \fIargv_in_out\fP 1.5i
 232 Specifies the command line arguments array.
 233 .IP \fIfallback_resources\fP 1.5i
 234 Specifies resource values to be used if the application class
 235 resource file cannot be opened, or NULL.
 236 .IP ... 1.5i
 237 Specifies the variable argument list to override any other
 238 resource specifications for the created shell.
 239 .LP
 240 .eM
 241 The
 242 .PN XtVaAppInitialize
 243 procedure is identical in function to
 244 .PN XtAppInitialize
 245 with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list,
 246 as described
 247 in Section 2.5.1.
 248 .sp
 249 .LP
 250 As a convenience to people converting from earlier versions of the toolkit
 251 without application contexts, the following routines exist:
 252 .PN XtInitialize ,
 253 .PN XtMainLoop ,
 254 .PN XtNextEvent ,
 255 .PN XtProcessEvent ,
 256 .PN XtPeekEvent ,
 257 .PN XtPending ,
 258 .PN XtAddInput ,
 259 .PN XtAddTimeOut ,
 260 .PN XtAddWorkProc ,
 261 .PN XtCreateApplicationShell ,
 262 .PN XtAddActions ,
 263 .PN XtSetSelectionTimeout ,
 264 and
 265 .PN XtGetSelectionTimeout .
 266 .LP
 267 .IN "XtInitialize" "" "@DEF@"
 268 .sM
 269 .FD 0
 270 Widget XtInitialize(\fIshell_name\fP, \fIapplication_class\fP, \fIoptions\fP, \
 271 \fInum_options\fP, \fIargc\fP, \fIargv\fP)
 272 .br
 273       String \fIshell_name\fP;
 274 .br
 275       String \fIapplication_class\fP;
 276 .br
 277       XrmOptionDescRec \fIoptions\fP[];
 278 .br
 279       Cardinal \fInum_options\fP;
 280 .br
 281       int *\fIargc\fP;
 282 .br
 283       String \fIargv\fP[];
 284 .FN
 285 .IP \fIshell_name\fP 1i
 286 This parameter is ignored; therefore, you can specify NULL.
 287 .IP \fIapplication_class\fP 1i
 288 Specifies the class name of this application.
 289 .IP \fIoptions\fP 1i
 290 Specifies how to parse the command line for any application-specific resources.
 291 The \fIoptions\fP argument is passed as a parameter to
 292 .PN XrmParseCommand .
 293 .IP \fInum_options\fP 1i
 294 Specifies the number of entries in the options list.
 295 .IP \fIargc\fP 1i
 296 Specifies a pointer to the number of command line parameters.
 297 .IP \fIargv\fP 1i
 298 Specifies the command line parameters.
 299 .LP
 300 .eM
 301 .PN XtInitialize
 302 calls
 303 .PN XtToolkitInitialize
 304 to initialize the toolkit internals,
 305 creates a default application context for use by the other convenience
 306 routines, calls
 307 .PN XtOpenDisplay
 308 with \fIdisplay_string\fP NULL and \fIapplication_name\fP NULL, and
 309 finally calls
 310 .PN XtAppCreateShell
 311 with \fIapplication_name\fP NULL and
 312 returns the created shell.
 313 The semantics of calling
 314 .PN XtInitialize
 315 more than once are undefined.
 316 This routine has been replaced by
 317 .PN XtOpenApplication .
 318 .sp
 319 .IN "XtMainLoop" "" "@DEF@"
 320 .sM
 321 .FD 0
 322 void XtMainLoop(void)
 323 .FN
 324 .LP
 325 .eM
 326 .PN XtMainLoop
 327 first reads the next alternate input, timer, or X event by calling
 328 .PN XtNextEvent .
 329 Then it dispatches this to the appropriate registered procedure by calling
 330 .PN XtDispatchEvent .
 331 This routine has been replaced by
 332 .PN XtAppMainLoop .
 333 .sp
 334 .IN "XtNextEvent" "" "@DEF@"
 335 .sM
 336 .FD 0
 337 void XtNextEvent(\fIevent_return\fP)
 338 .br
 339       XEvent *\fIevent_return\fP;
 340 .FN
 341 .IP \fIevent_return\fP 1i
 342 Returns the event information to the specified event structure.
 343 .LP
 344 .eM
 345 If no input is on the X input queue for the default application context,
 346 .PN XtNextEvent
 347 flushes the X output buffer
 348 and waits for an event while looking at the alternate input sources
 349 and timeout values and calling any callback procedures triggered by them.
 350 This routine has been replaced by
 351 .PN XtAppNextEvent .
 352 .PN XtInitialize
 353 must be called before using this routine.
 354 .sp
 355 .IN "XtProcessEvent" "" "@DEF@"
 356 .sM
 357 .FD 0
 358 void XtProcessEvent(\fImask\fP)
 359 .br
 360       XtInputMask \fImask\fP;
 361 .FN
 362 .IP \fImask\fP 1i
 363 Specifies the type of input to process.
 364 .LP
 365 .eM
 366 .PN XtProcessEvent
 367 processes one X event, timeout, or alternate input source
 368 (depending on the value of \fImask\fP), blocking if necessary.
 369 It has been replaced by
 370 .PN XtAppProcessEvent .
 371 .PN XtInitialize
 372 must be called before using this function.
 373 .sp
 374 .IN "XtPeekEvent" "" "@DEF@"
 375 .sM
 376 .FD 0
 377 Boolean XtPeekEvent(\fIevent_return\fP)
 378 .br
 379       XEvent *\fIevent_return\fP;
 380 .FN
 381 .IP \fIevent_return\fP 1i
 382 Returns the event information to the specified event structure.
 383 .LP
 384 .eM
 385 If there is an event in the queue for the default application context,
 386 .PN XtPeekEvent
 387 fills in the event and returns a nonzero value.
 388 If no X input is on the queue,
 389 .PN XtPeekEvent
 390 flushes the output buffer and blocks until input is available, possibly
 391 calling some timeout callbacks in the process.
 392 If the input is an event,
 393 .PN XtPeekEvent
 394 fills in the event and returns a nonzero value.
 395 Otherwise, the input is for an alternate input source, and
 396 .PN XtPeekEvent
 397 returns zero.
 398 This routine has been replaced by
 399 .PN XtAppPeekEvent .
 400 .PN XtInitialize
 401 must be called before using this routine.
 402 .sp
 403 .IN "XtPending" "" "@DEF@"
 404 .sM
 405 .FD 0
 406 Boolean XtPending()
 407 .FN
 408 .LP
 409 .eM
 410 .PN XtPending
 411 returns a nonzero value if there are
 412 events pending from the X server or alternate input sources in the default
 413 application context.
 414 If there are no events pending,
 415 it flushes the output buffer and returns a zero value.
 416 It has been replaced by
 417 .PN XtAppPending .
 418 .PN XtInitialize
 419 must be called before using this routine.
 420 .sp
 421 .IN "XtAddInput" "" "@DEF@"
 422 .sM
 423 .FD 0
 424 XtInputId XtAddInput(\fIsource\fP, \fIcondition\fP, \fIproc\fP, \
 425 \fIclient_data\fP)
 426 .br
 427       int \fIsource\fP;
 428 .br
 429       XtPointer \fIcondition\fP;
 430 .br
 431       XtInputCallbackProc \fIproc\fP;
 432 .br
 433       XtPointer \fIclient_data\fP;
 434 .FN
 435 .IP \fIsource\fP 1i
 436 Specifies the source file descriptor on a POSIX-based system
 437 or other operating-system-dependent device specification.
 438 .IP \fIcondition\fP 1i
 439 Specifies the mask that indicates either a read, write, or exception condition
 440 or some operating-system-dependent condition.
 441 .IP \fIproc\fP 1i
 442 Specifies the procedure called when input is available.
 443 .IP \fIclient_data\fP 1i
 444 Specifies the parameter to be passed to \fIproc\fP when input is available.
 445 .LP
 446 .eM
 447 The
 448 .PN XtAddInput
 449 function registers in the default application context a new
 450 source of events,
 451 which is usually file input but can also be file output.
 452 (The word \fIfile\fP should be loosely interpreted to mean any sink
 453 or source of data.)
 454 .PN XtAddInput
 455 also specifies the conditions under which the source can generate events.
 456 When input is pending on this source in the default application context,
 457 the callback procedure is called.
 458 This routine has been replaced by
 459 .PN XtAppAddInput .
 460 .PN XtInitialize
 461 must be called before using this routine.
 462 .sp
 463 .IN "XtAddTimeOut" "" "@DEF@"
 464 .sM
 465 .FD 0
 466 XtIntervalId XtAddTimeOut(\fIinterval\fP, \fIproc\fP, \fIclient_data\fP)
 467 .br
 468       unsigned long \fIinterval\fP;
 469 .br
 470       XtTimerCallbackProc \fIproc\fP;
 471 .br
 472       XtPointer \fIclient_data\fP;
 473 .FN
 474 .IP \fIinterval\fP 1i
 475 Specifies the time interval in milliseconds.
 476 .IP \fIproc\fP 1i
 477 Specifies the procedure to be called when time expires.
 478 .IP \fIclient_data\fP 1i
 479 Specifies the parameter to be passed to \fIproc\fP when it is called.
 480 .LP
 481 .eM
 482 The
 483 .PN XtAddTimeOut
 484 function creates a timeout in the default application context
 485 and returns an identifier for it.
 486 The timeout value is set to \fIinterval\fP.
 487 The callback procedure will be called after
 488 the time interval elapses, after which the timeout is removed.
 489 This routine has been replaced by
 490 .PN XtAppAddTimeOut .
 491 .PN XtInitialize
 492 must be called before using this routine.
 493 .sp
 494 .IN "XtAddWorkProc" "" "@DEF@"
 495 .sM
 496 .FD 0
 497 XtWorkProcId XtAddWorkProc(\fIproc\fP, \fIclient_data\fP)
 498 .br
 499       XtWorkProc \fIproc\fP;
 500 .br
 501       XtPointer \fIclient_data\fP;
 502 .FN
 503 .IP \fIproc\fP 1i
 504 Procedure to call to do the work.
 505 .IP \fIclient_data\fP 1i
 506 Client data to pass to \fIproc\fP when it is called.
 507 .LP
 508 .eM
 509 This routine registers a work procedure in the default application context. It has
 510 been replaced by
 511 .PN XtAppAddWorkProc .
 512 .PN XtInitialize
 513 must be called before using this routine.
 514 .sp
 515 .IN "XtCreateApplicationShell" "" "@DEF@"
 516 .sM
 517 .FD 0
 518 Widget XtCreateApplicationShell(\fIname\fP, \fIwidget_class\fP, \fIargs\fP, \
 519 \fInum_args\fP)
 520 .br
 521       String \fIname\fP;
 522 .br
 523       WidgetClass \fIwidget_class\fP;
 524 .br
 525       ArgList \fIargs\fP;
 526 .br
 527       Cardinal \fInum_args\fP;
 528 .FN
 529 .IP \fIname\fP 1i
 530 This parameter is ignored; therefore, you can specify NULL.
 531 .IP \fIwidget_class\fP 1i
 532 Specifies the widget class pointer for the created application shell widget.
 533 This will usually be
 534 .PN topLevelShellWidgetClass
 535 or a subclass thereof.
 536 .IP \fIargs\fP 1i
 537 Specifies the argument list to override  any other resource specifications.
 538 .IP \fInum_args\fP 1i
 539 Specifies the number of entries in \fIargs\fP.
 540 .LP
 541 .eM
 542 The procedure
 543 .PN XtCreateApplicationShell
 544 calls
 545 .PN XtAppCreateShell
 546 with \fIapplication_name\fP NULL, the application class passed to
 547 .PN XtInitialize ,
 548 and the default application context created by
 549 .PN XtInitialize .
 550 This routine has been replaced by
 551 .PN XtAppCreateShell .
 552 .sp
 553 .LP
 554 An old-format resource type converter procedure pointer is of type
 555 .PN XtConverter .
 556 .LP
 557 .IN "XtConverter" "" "@DEF@"
 558 .sM
 559 .FD 0
 560 typedef void (*XtConverter)(XrmValue*, Cardinal*, XrmValue*, XrmValue*);
 561 .br
 562       XrmValue *\fIargs\fP;
 563 .br
 564       Cardinal *\fInum_args\fP;
 565 .br
 566       XrmValue *\fIfrom\fP;
 567 .br
 568       XrmValue *\fIto\fP;
 569 .FN
 570 .IP \fIargs\fP 1i
 571 Specifies a list of additional
 572 .PN XrmValue
 573 arguments to the converter if additional context is needed
 574 to perform the conversion, or NULL.
 575 .IP \fInum_args\fP 1i
 576 Specifies the number of entries in \fIargs\fP.
 577 .IP \fIfrom\fP 1i
 578 Specifies the value to convert.
 579 .IP \fIto\fP 1i
 580 Specifies the descriptor to use to return the converted value.
 581 .LP
 582 .eM
 583 Type converters should perform the following actions:
 584 .IP \(bu 5
 585 Check to see that the number of arguments passed is correct.
 586 .IP \(bu 5
 587 Attempt the type conversion.
 588 .IP \(bu 5
 589 If successful, return the size and pointer to the data in the \fIto\fP argument;
 590 otherwise, call
 591 .PN XtWarningMsg
 592 and return without modifying the \fIto\fP argument.
 593 .LP
 594 Most type converters just take the data described by the specified \fIfrom\fP
 595 argument and return data by writing into the specified \fIto\fP argument.
 596 A few need other information, which is available in the specified
 597 argument list.
 598 A type converter can invoke another type converter,
 599 which allows differing sources that may convert into a common intermediate
 600 result to make maximum use of the type converter cache.
 601 .LP
 602 Note that the address returned in \fIto->addr\fP cannot be that of a local variable of
 603 the converter because this is not valid after the converter returns.
 604 It should be a pointer to a static variable.
 605 .LP
 606 The procedure type
 607 .PN XtConverter
 608 has been replaced by
 609 .PN XtTypeConverter .
 610 .sp
 611 .LP
 612 The
 613 .PN XtStringConversionWarning
 614 .IN "XtStringConversionWarning" "" "@DEF@"
 615 function is a convenience routine for old-format resource converters
 616 that convert from strings.
 617 .LP
 618 .sM
 619 .FD 0
 620 void XtStringConversionWarning(\fIsrc\fP, \fIdst_type\fP)
 621 .br
 622       String \fIsrc\fP, \fIdst_type\fP;
 623 .FN
 624 .IP \fIsrc\fP 1i
 625 Specifies the string that could not be converted.
 626 .IP \fIdst_type\fP 1i
 627 Specifies the name of the type to which the string could not be converted.
 628 .LP
 629 .eM
 630 The
 631 .PN XtStringConversionWarning
 632 function issues a warning message with name ``conversionError'',
 633 type ``string'', class ``XtToolkitError, and the default message string
 634 ``Cannot convert "\fIsrc\fP" to type \fIdst_type\fP''.  This routine
 635 has been superseded by
 636 .PN XtDisplayStringConversionWarning .
 637 .sp
 638 .LP
 639 To register an old-format converter, use
 640 .PN XtAddConverter
 641 .IN "XtAddConverter" "" "@DEF@"
 642 or
 643 .PN XtAppAddConverter .
 644 .IN "XtAppAddConverter" "" "@DEF@"
 645 .LP
 646 .sM
 647 .FD 0
 648 void XtAddConverter(\fIfrom_type\fP, \fIto_type\fP, \fIconverter\fP, \
 649 \fIconvert_args\fP, \fInum_args\fP)
 650 .br
 651       String \fIfrom_type\fP;
 652 .br
 653       String \fIto_type\fP;
 654 .br
 655       XtConverter \fIconverter\fP;
 656 .br
 657       XtConvertArgList \fIconvert_args\fP;
 658 .br
 659       Cardinal \fInum_args\fP;
 660 .FN
 661 .IP \fIfrom_type\fP 1i
 662 Specifies the source type.
 663 .IP \fIto_type\fP 1i
 664 Specifies the destination type.
 665 .IP \fIconverter\fP 1i
 666 Specifies the type converter procedure.
 667 .IP \fIconvert_args\fP 1i
 668 Specifies how to compute the additional arguments to the converter, or NULL.
 669 .IP \fInum_args\fP 1i
 670 Specifies the number of entries in \fIconvert_args\fP.
 671 .sp
 672 .LP
 673 .eM
 674 .PN XtAddConverter
 675 is equivalent in function to
 676 .PN XtSetTypeConverter
 677 with \fIcache_type\fP equal to
 678 .PN XtCacheAll
 679 for old-format type converters.  It has been superseded by
 680 .PN XtSetTypeConverter .
 681 .sp
 682 .sM
 683 .FD 0
 684 void XtAppAddConverter(\fIapp_context\fP, \fIfrom_type\fP, \fIto_type\fP, \
 685 \fIconverter\fP, \fIconvert_args\fP, \fInum_args\fP)
 686 .br
 687       XtAppContext \fIapp_context\fP;
 688 .br
 689       String \fIfrom_type\fP;
 690 .br
 691       String \fIto_type\fP;
 692 .br
 693       XtConverter \fIconverter\fP;
 694 .br
 695       XtConvertArgList \fIconvert_args\fP;
 696 .br
 697       Cardinal \fInum_args\fP;
 698 .FN
 699 .IP \fIapp_context\fP 1i
 700 Specifies the application context.
 701 .IP \fIfrom_type\fP 1i
 702 Specifies the source type.
 703 .IP \fIto_type\fP 1i
 704 Specifies the destination type.
 705 .IP \fIconverter\fP 1i
 706 Specifies the type converter procedure.
 707 .IP \fIconvert_args\fP 1i
 708 Specifies how to compute the additional arguments to the converter, or NULL.
 709 .IP \fInum_args\fP 1i
 710 Specifies the number of entries in \fIconvert_args\fP.
 711 .LP
 712 .eM
 713 .PN XtAppAddConverter
 714 is equivalent in function to
 715 .PN XtAppSetTypeConverter
 716 with \fIcache_type\fP equal to
 717 .PN XtCacheAll
 718 for old-format type converters.  It has been superseded by
 719 .PN XtAppSetTypeConverter .
 720 .sp
 721 .LP
 722 To invoke resource conversions, a client may use
 723 .PN XtConvert
 724 or, for old-format converters only,
 725 .PN XtDirectConvert .
 726 .LP
 727 .IN "XtConvert" "" "@DEF@"
 728 .sM
 729 .FD 0
 730 void XtConvert(\fIw\fP, \fIfrom_type\fP, \fIfrom\fP, \fIto_type\fP, \
 731 \fIto_return\fP)
 732 .br
 733       Widget \fIw\fP;
 734 .br
 735       String \fIfrom_type\fP;
 736 .br
 737       XrmValuePtr \fIfrom\fP;
 738 .br
 739       String \fIto_type\fP;
 740 .br
 741       XrmValuePtr \fIto_return\fP;
 742 .FN
 743 .IP \fIw\fP 1i
 744 Specifies the widget to use for additional arguments, if any are
 745 needed.
 746 .IP \fIfrom_type\fP 1i
 747 Specifies the source type.
 748 .IP \fIfrom\fP 1i
 749 Specifies the value to be converted.
 750 .IP \fIto_type\fP 1i
 751 Specifies the destination type.
 752 .IP \fIto_return\fP 1i
 753 Returns the converted value.
 754 .LP
 755 .IN "XtDirectConvert" "" "@DEF@"
 756 .FD 0
 757 void XtDirectConvert(\fIconverter\fP, \fIargs\fP, \fInum_args\fP, \fIfrom\fP, \
 758 \fIto_return\fP)
 759 .br
 760       XtConverter \fIconverter\fP;
 761 .br
 762       XrmValuePtr \fIargs\fP;
 763 .br
 764       Cardinal \fInum_args\fP;
 765 .br
 766       XrmValuePtr \fIfrom\fP;
 767 .br
 768       XrmValuePtr \fIto_return\fP;
 769 .FN
 770 .IP \fIconverter\fP 1i
 771 Specifies the conversion procedure to be called.
 772 .IP \fIargs\fP 1i
 773 Specifies the argument list that contains the additional arguments
 774 needed to perform the conversion (often NULL).
 775 .IP \fInum_args\fP 1i
 776 Specifies the number of entries in \fIargs\fP.
 777 .IP \fIfrom\fP 1i
 778 Specifies the value to be converted.
 779 .IP \fIto_return\fP 1i
 780 Returns the converted value.
 781 .LP
 782 .eM
 783 The
 784 .PN XtConvert
 785 function looks up the type converter registered to convert \fIfrom_type\fP
 786 to \fIto_type\fP, computes any additional arguments needed, and then calls
 787 .PN XtDirectConvert
 788 or
 789 .PN XtCallConverter .
 790 The
 791 .PN XtDirectConvert
 792 function looks in the converter cache to see if this conversion procedure
 793 has been called with the specified arguments.
 794 If so, it returns a descriptor for information stored in the cache;
 795 otherwise, it calls the converter and enters the result in the cache.
 796 .LP
 797 Before calling the specified converter,
 798 .PN XtDirectConvert
 799 sets the return value size to zero and the return value address to NULL.
 800 To determine if the conversion was successful,
 801 the client should check \fIto_return.addr\fP for non-NULL.
 802 The data returned by
 803 .PN XtConvert
 804 must be copied immediately by the caller,
 805 as it may point to static data in the type converter.
 806 .LP
 807 .PN XtConvert
 808 has been replaced by
 809 .PN XtConvertAndStore ,
 810 and
 811 .PN XtDirectConvert
 812 has been superseded by
 813 .PN XtCallConverter .
 814 .sp
 815 .LP
 816 To deallocate a shared GC when it is no longer needed, use
 817 .PN XtDestroyGC .
 818 .LP
 819 .IN "XtDestroyGC" "" "@DEF@"
 820 .sM
 821 .FD 0
 822 void XtDestroyGC(\fIw\fP, \fIgc\fP)
 823 .br
 824       Widget \fIw\fP;
 825 .br
 826       GC \fIgc\fP;
 827 .FN
 828 .IP \fIw\fP 1i
 829 Specifies any object on the display for which the shared GC was
 830 created.  \*(oI
 831 .IP \fIgc\fP 1i
 832 Specifies the shared GC to be deallocated.
 833 .LP
 834 .eM
 835 References to sharable GCs are counted and a free request is generated to the
 836 server when the last user of a given GC destroys it.
 837 Note that some earlier versions of
 838 .PN XtDestroyGC
 839 had only a \fIgc\fP argument.
 840 Therefore, this function is not very portable,
 841 and you are encouraged to use
 842 .PN XtReleaseGC
 843 instead.
 844 .sp
 845 .LP
 846 To declare an action table in the default application context
 847 and register it with the translation manager, use
 848 .PN XtAddActions .
 849 .LP
 850 .IN "XtAddActions" "" "@DEF@"
 851 .sM
 852 .FD 0
 853 void XtAddActions(\fIactions\fP, \fInum_actions\fP)
 854 .br
 855       XtActionList \fIactions\fP;
 856 .br
 857       Cardinal \fInum_actions\fP;
 858 .FN
 859 .IP \fIactions\fP 1i
 860 Specifies the action table to register.
 861 .IP \fInum_actions\fP 1i
 862 Specifies the number of entries in \fIactions\fP.
 863 .LP
 864 .eM
 865 If more than one action is registered with the same name,
 866 the most recently registered action is used.
 867 If duplicate actions exist in an action table,
 868 the first is used.
 869 The \*(xI register an action table for
 870 .PN XtMenuPopup
 871 and
 872 .PN XtMenuPopdown
 873 as part of \*(tk initialization.
 874 This routine has been replaced by
 875 .PN XtAppAddActions .
 876 .PN XtInitialize
 877 must be called before using this routine.
 878 .sp
 879 .LP
 880 To set the \*(xI selection timeout in the default application context, use
 881 .PN XtSetSelectionTimeout .
 882 .LP
 883 .IN "XtSetSelectionTimeout" "" "@DEF@"
 884 .sM
 885 .FD 0
 886 void XtSetSelectionTimeout(\fItimeout\fP)
 887 .br
 888       unsigned long \fItimeout\fP;
 889 .FN
 890 .IP \fItimeout\fP 1i
 891 Specifies the selection timeout in milliseconds.
 892 This routine has been replaced by
 893 .PN XtAppSetSelectionTimeout .
 894 .PN XtInitialize
 895 must be called before using this routine.
 896 .LP
 897 .eM
 898 .sp
 899 .LP
 900 To get the current selection timeout value in the default application
 901 context, use
 902 .PN XtGetSelectionTimeout .
 903 .LP
 904 .IN "XtGetSelectionTimeout" "" "@DEF@"
 905 .sM
 906 .FD 0
 907 unsigned long XtGetSelectionTimeout()
 908 .FN
 909 .LP
 910 .eM
 911 The selection timeout is the time within which the two communicating
 912 applications must respond to one another.
 913 If one of them does not respond within this interval,
 914 the \*(xI abort the selection request.
 915 .LP
 916 This routine has been replaced by
 917 .PN XtAppGetSelectionTimeout .
 918 .PN XtInitialize
 919 must be called before using this routine.
 920 .sp
 921 .LP
 922 To obtain the global error database (for example, to merge with
 923 an application- or widget-specific database), use
 924 .PN XtGetErrorDatabase .
 925 .LP
 926 .IN "XtGetErrorDatabase" "" "@DEF@"
 927 .sM
 928 .FD 0
 929 XrmDatabase *XtGetErrorDatabase()
 930 .FN
 931 .LP
 932 .eM
 933 The
 934 .PN XtGetErrorDatabase
 935 function returns the address of the error database.
 936 The \*(xI do a lazy binding of the error database and do not merge in the
 937 database file until the first call to
 938 .PN XtGetErrorDatbaseText .
 939 This routine has been replaced by
 940 .PN XtAppGetErrorDatabase .
 941 .sp
 942 .LP
 943 An error message handler can obtain the error database text for an
 944 error or a warning by calling
 945 .PN XtGetErrorDatabaseText .
 946 .LP
 947 .IN "XtGetErrorDatabaseText" "" "@DEF@"
 948 .sM
 949 .FD 0
 950 void XtGetErrorDatabaseText(\fIname\fP, \fItype\fP, \fIclass\fP, \
 951 \fIdefault\fP, \fIbuffer_return\fP, \fInbytes\fP)
 952 .br
 953       String \fIname\fP, \fItype\fP, \fIclass\fP;
 954 .br
 955       String \fIdefault\fP;
 956 .br
 957       String \fIbuffer_return\fP;
 958 .br
 959       int \fInbytes\fP;
 960 .FN
 961 .IP \fIname\fP 1i
 962 .br
 963 .ns
 964 .IP \fItype\fP 1i
 965 Specify the name and type that are concatenated to form the resource name
 966 of the error message.
 967 .IP \fIclass\fP 1i
 968 Specifies the resource class of the error message.
 969 .IP \fIdefault\fP 1i
 970 Specifies the default message to use if an error database entry is not found.
 971 .IP \fIbuffer_return\fP 1i
 972 Specifies the buffer into which the error message is to be returned.
 973 .IP \fInbytes\fP 1i
 974 Specifies the size of the buffer in bytes.
 975 .LP
 976 .eM
 977 The
 978 .PN XtGetErrorDatabaseText
 979 returns the appropriate message from the error database
 980 associated with the default application context
 981 or returns the specified default message if one is not found in the
 982 error database.
 983 To form the full resource name and class when querying the database,
 984 the \fIname\fP and \fItype\fP are concatenated with a single ``.''
 985 between them and the \fIclass\fP is concatenated with itself with a
 986 single ``.'' if it does not already contain a ``.''.
 987 This routine has been superseded by
 988 .PN XtAppGetErrorDatabaseText .
 989 .sp
 990 .LP
 991 To register a procedure to be called on fatal error conditions, use
 992 .PN XtSetErrorMsgHandler .
 993 .LP
 994 .IN "XtSetErrorMsgHandler" "" "@DEF@"
 995 .sM
 996 .FD 0
 997 void XtSetErrorMsgHandler(\fImsg_handler\fP)
 998 .br
 999       XtErrorMsgHandler \fImsg_handler\fP;
1000 .FN
1001 .IP \fImsg_handler\fP 1i
1002 Specifies the new fatal error procedure, which should not return.
1003 .LP
1004 .eM
1005 The default error handler provided by the \*(xI constructs a
1006 string from the error resource database and calls
1007 .PN XtError .
1008 Fatal error message handlers should not return.
1009 If one does,
1010 subsequent \*(xI behavior is undefined.
1011 This routine has been superseded by
1012 .PN XtAppSetErrorMsgHandler .
1013 .sp
1014 .LP
1015 To call the high-level error handler, use
1016 .PN XtErrorMsg .
1017 .LP
1018 .IN "XtErrorMsg" "" "@DEF@"
1019 .sM
1020 .FD 0
1021 void XtErrorMsg(\fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \
1022 \fIparams\fP, \fInum_params\fP)
1023 .br
1024       String \fIname\fP;
1025 .br
1026       String \fItype\fP;
1027 .br
1028       String \fIclass\fP;
1029 .br
1030       String \fIdefault\fP;
1031 .br
1032       String *\fIparams\fP;
1033 .br
1034       Cardinal *\fInum_params\fP;
1035 .FN
1036 .IP \fIname\fP 1i
1037 Specifies the general kind of error.
1038 .IP \fItype\fP 1i
1039 Specifies the detailed name of the error.
1040 .IP \fIclass\fP 1i
1041 Specifies the resource class.
1042 .IP \fIdefault\fP 1i
1043 Specifies the default message to use if an error database entry is not found.
1044 .IP \fIparams\fP 1i
1045 Specifies a pointer to a list of values to be stored in the message.
1046 .IP \fInum_params\fP 1i
1047 Specifies the number of entries in \fIparams\fP.
1048 .LP
1049 .eM
1050 This routine has been superseded by
1051 .PN XtAppErrorMsg .
1052 .sp
1053 .LP
1054 To register a procedure to be called on nonfatal error conditions, use
1055 .PN XtSetWarningMsgHandler .
1056 .LP
1057 .IN "XtSetWarningMsgHandler" "" "@DEF@"
1058 .sM
1059 .FD 0
1060 void XtSetWarningMsgHandler(\fImsg_handler\fP)
1061 .br
1062       XtErrorMsgHandler \fImsg_handler\fP;
1063 .FN
1064 .IP \fImsg_handler\fP 1i
1065 Specifies the new nonfatal error procedure, which usually returns.
1066 .LP
1067 .eM
1068 The default warning handler provided by the \*(xI constructs a string
1069 from the error resource database and calls
1070 .PN XtWarning .
1071 This routine has been superseded by
1072 .PN XtAppSetWarningMsgHandler .
1073 .sp
1074 .LP
1075 To call the installed high-level warning handler, use
1076 .PN XtWarningMsg .
1077 .LP
1078 .IN "XtWarningMsg" "" "@DEF@"
1079 .sM
1080 .FD 0
1081 void XtWarningMsg(\fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \
1082 \fIparams\fP, \fInum_params\fP)
1083 .br
1084       String \fIname\fP;
1085 .br
1086       String \fItype\fP;
1087 .br
1088       String \fIclass\fP;
1089 .br
1090       String \fIdefault\fP;
1091 .br
1092       String *\fIparams\fP;
1093 .br
1094       Cardinal *\fInum_params\fP;
1095 .FN
1096 .IP \fIname\fP 1i
1097 Specifies the general kind of error.
1098 .IP \fItype\fP 1i
1099 Specifies the detailed name of the error.
1100 .IP \fIclass\fP 1i
1101 Specifies the resource class.
1102 .IP \fIdefault\fP 1i
1103 Specifies the default message to use if an error database entry is not found.
1104 .IP \fIparams\fP 1i
1105 Specifies a pointer to a list of values to be stored in the message.
1106 .IP \fInum_params\fP 1i
1107 Specifies the number of entries in \fIparams\fP.
1108 .LP
1109 .eM
1110 This routine has been superseded by
1111 .PN XtAppWarningMsg .
1112 .sp
1113 .LP
1114 To register a procedure to be called on fatal error conditions, use
1115 .PN XtSetErrorHandler .
1116 .LP
1117 .IN "XtSetErrorHandler" "" "@DEF@"
1118 .sM
1119 .FD 0
1120 void XtSetErrorHandler(\fIhandler\fP)
1121 .br
1122       XtErrorHandler \fIhandler\fP;
1123 .FN
1124 .IP \fIhandler\fP 1i
1125 Specifies the new fatal error procedure, which should not return.
1126 .LP
1127 .eM
1128 The default error handler provided by the \*(xI is
1129 .PN _XtError .
1130 On POSIX-based systems,
1131 it prints the message to standard error and terminates the application.
1132 Fatal error message handlers should not return.
1133 If one does,
1134 subsequent \*(tk behavior is undefined.
1135 This routine has been superseded by
1136 .PN XtAppSetErrorHandler .
1137 .sp
1138 .LP
1139 To call the installed fatal error procedure, use
1140 .PN XtError .
1141 .LP
1142 .IN "XtError" "" "@DEF@"
1143 .sM
1144 .FD 0
1145 void XtError(\fImessage\fP)
1146 .br
1147       String \fImessage\fP;
1148 .FN
1149 .IP \fImessage\fP 1i
1150 Specifies the message to be reported.
1151 .LP
1152 .eM
1153 Most programs should use
1154 .PN XtAppErrorMsg ,
1155 not
1156 .PN XtError ,
1157 to provide for customization and internationalization of error
1158 messages.  This routine has been superseded by
1159 .PN XtAppError .
1160 .sp
1161 .LP
1162 To register a procedure to be called on nonfatal error conditions, use
1163 .PN XtSetWarningHandler .
1164 .LP
1165 .IN "XtSetWarningHandler" "" "@DEF@"
1166 .sM
1167 .FD 0
1168 void XtSetWarningHandler(\fIhandler\fP)
1169 .br
1170       XtErrorHandler \fIhandler\fP;
1171 .FN
1172 .IP \fIhandler\fP 1i
1173 Specifies the new nonfatal error procedure, which usually returns.
1174 .LP
1175 .eM
1176 The default warning handler provided by the \*(xI is
1177 .PN _XtWarning .
1178 On POSIX-based systems,
1179 it prints the message to standard error and returns to the caller.
1180 This routine has been superseded by
1181 .PN XtAppSetWarningHandler .
1182 .sp
1183 .LP
1184 To call the installed nonfatal error procedure, use
1185 .PN XtWarning .
1186 .LP
1187 .IN "XtWarning" "" "@DEF@"
1188 .sM
1189 .FD 0
1190 void XtWarning(\fImessage\fP)
1191 .br
1192       String \fImessage\fP;
1193 .FN
1194 .IP \fImessage\fP 1i
1195 Specifies the nonfatal error message to be reported.
1196 .LP
1197 .eM
1198 Most programs should use
1199 .PN XtAppWarningMsg ,
1200 not
1201 .PN XtWarning ,
1202 to provide for customization and internationalization of warning messages.
1203 This routine has been superseded by
1204 .PN XtAppWarning .