REF XT_APPINIT Adrian Howard Jun 1991 Updated Jason Handby Aug 1991 COPYRIGHT University of Sussex 1990. All Rights Reserved. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< CONVENIENCE INITIALISATION >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< OF APPLICATIONS >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< This REF file details the procedures that are supplied by the two library packages LIB * XT_APPINIT and LIB * FAST_XT_APPINIT which provide the Pop-11 interface to the various X Toolkit convenience routines for initialising an application. CONTENTS - (Use g to access required sections) 1 Introduction 2 LIB XT_APPINIT 3 LIB FAST_XT_APPINIT --------------- 1 Introduction --------------- Various initialisation actions need to be performed when an application is started. The Toolkit internals must be initialised, an application context needs to be created, a connection must be established with a display server, and a shell widget must be created (which will be the parent widget of the application). The library LIB * XT_APPINIT provides the Pop-11 interface to the various X Toolkit convenience routines for initialising an application. The library LIB * FAST_XT_APPINIT (loaded by LIB * XT_APPINIT) provides a non-type checking interface to the same procedures. The procedures provided allow the following functions to be performed in a single procedure call: o The initialisation of the X Toolkit Internals o The creation of a default application context o The opening and the initialisation of a display o The creation of an initial application shell instance The exact structure of arguments and results for the following procedures is as discussed in REF * XPT_TYPES. For full details see section 2.4.4 of: X Toolkit Intrinsics - C Language Interface X Window System X Version 11, Release 4 Copyright (C) 1985, 1986, 1987, 1988, Massachusetts Institute of Technology, Cambridge, Massachusetts, and Digital Equipment Corporation, Maynard, Massachusetts. ----------------- 2 LIB XT_APPINIT ----------------- XptAppContextPtr [shadowclass typespec] This declaration provides support for the XptAppContextPtr shadowclass structure containing a single XptACPValue field, pointing to an XptAppContext record. Its external_ptr_props are set to the constant XDT_VALUEPTR (see REF * XPT_CONSTANTS) to enable "weak" type checking (See REF * XptDescriptor for more details). shadowclass XptAppContextPtr [props ^XDT_APPCONTEXTPTR] {XptACPValue :XptAppContext}; XptACPValue(appcontextptr) -> appcontext [procedure] appcontext -> XptACPValue(appcontextptr) Access or update the application context appcontext referred to by the XptAppContextPtr shadowclass record appcontextptr. A value of false can be returned/passed to the procedure to indicate a null application context. isXptAppContextPtr(item) -> bool [procedure] Checks to see whether item is an instance of an XptAppContextPtr shadowclass record, and returns true or false accordingly. initXptAppContextPtr() -> appcontextptr [procedure] Creates a new instance of an XptAppContextPtr shadowclass record with a false XptACPValue field. fillXptAppContextPtr(appcontext, appcontextptr) [procedure] -> appcontextptr Fills an existing XptAppContextPtr record appcontextptr with the application context appcontext, and returns the newly-filled object. appcontext being false indicates a null application context. consXptAppContextPtr(appcontext) -> appcontextptr [procedure] Constructs an instance of the XptAppContextPtr shadowclass with an XptACPValue field of appcontext. A value of false indicates a null application context. destXptAppContextPtr(appcontextptr) -> appcontext [procedure] Given an instance of an XptAppContextPtr shadowclass record, stacks its XptACPValue field. appcontext is false when the application context pointed to by appcontextptr is null. importXptAppContextPtr(exptrclass) -> appcontextptr [procedure] Given an external pointer class record exptrclass, that points to the address of an application context, the procedure returns an XptAppContextPtr shadowclass record appcontextptr whose XptACPValue field is the application context referred to by exptrclass. refreshXptAppContextPtr(appcontextptr) -> appcontextptr [procedure] Refresh the contents of the XptAppContextPtr object appcontextptr from the external copy, returning the refreshed object. XptAppContextPtr_shadowkey -> shkey [constant] Holds the shadowkey for the shadowclass XptAppContextPtr. XtAppInitialize(appcontextptr, app_class, [procedure] optiondesclist, num_options, argc_io, argv_io, fallback_resources, args, num_args) -> widget This procedure initialises the toolkit, creates an application context, opens a display connection, and creates an initial application shell widget widget. If appcontextptr is false then the application context created by the procedure is not returned. Otherwise, appcontextptr will be altered to point to the newly-created application context. The procedure refreshXptAppContextPtr should be used to update appcontextptr to reflect the amended value. app_class is a string specifying the class name of the application (see REF * XPT_TYPES). optiondesclist is an XptOptionDescList structure that specifies how the command line arguments are to be parsed. See REF * XPT_GENERALTYPES for a full explanation of the format of the structure. num_options is a CARDINAL that specifies the number of options in optiondesclist. argv_io is an XptStringList structure containing the command line arguments ('-display', '-geometry', etc). argc_io is an XptCardinalPtr pointing to the number of command line arguments that are stored in argv_io. After the call to XtAppInitialize the variable XptUnprocessedArgs will contain a list of any command line arguments that were not successfully parsed. If some of the command line arguments were not parsed successfully the usual response would be for the caller of XtAppInitialize to display the unparsed arguments along with a list of the legal command line options. NOTE: if you refresh argc_io and argv_io with refreshXptCardinalPtr and refreshXptStringList they will also contain any command line arguments that were not parsed, plus (on Unix systems) the command used to invoke the program. fallback_resources is a null-terminated XptStringList shadowclass structure containing resource values to be used if the application class resource file cannot be read. Each string in STRINGLIST should form a name-value pair of the form 'NAME:VALUE'. For example, to set the fallback geometry of the application 'Foo' to '100x100+2+3' you could use the XptStringList returned by: consXptStringList(#| 'Foo.geometry:100x100+2+2', false |#) If fallback_resources is false then no fallback resources are available. Finally, the XptArgList shadowclass structure args, of length num_args, contains resource values that will override any other resource specifications for the created shell widget. The args and num_args arguments can be replaced by a single Pop11 list or vector which will be coerced into an XptArgList structure (and length), using the XptArgList procedure. The procedure-XtAppInitialize- calls several Toolkit routines in order to perform the appropriate initialization actions. They are: XtToolkitInitialize see REF * XT_INIT. XtCreateApplicationContext see REF * XT_APPCON XtAppSetFallbackResources (if FALLBACKRESOURCES was non-false) see REF * XT_APPCON XtOpenDisplay (with a NULL display string and application name) see REF * XT_DISPLAY XtAppCreateShell (with a NULL application name, and a widget_class of applicationShellWidgetClass) see REF * XT_WIDGET Compare with XptDefaultSetup. XtVaAppInitialize(appcontextptr_return, app_class, [procedure] options, num_options, argc_io, argv_io, fallback_resources, varargs) -> widget This procedure performs the same function as the previous one, but expects its final resource list arguments in varargs format. (See REF * XPT_TYPES/varargs for a more detailed description of varargs.) The procedure XptVaArgList provides a simple way of creating varargs lists (REF * XT_LIBS/XptVaArgList). ---------------------- 3 LIB FAST_XT_APPINIT ---------------------- fast_XtAppInitialize(appcontextptr_return, app_class, [procedure] options, num_options, argc_io, argv_io, fallback_resources, args, num_args) -> widget fast_XtVaAppInitialize(appcontextptr_return, app_class, [procedure] options, num_options, argc_io, argv_io, fallback_resources, varargs) -> widget As for the procedures in LIB * XT_APPINIT, but without checks for valid arguments. Also, note that no automatic coercion of Pop11 lists/vectors to XptArgList structures will be performed. These procedures should only be used in fully debugged programs. See REF * XTOOLKIT for full details of the Poplog X naming conventions for non-checking and checking procedures. --- C.x/x/pop/ref/xt_appinit --- Copyright University of Sussex 1990. All rights reserved.