REF XT_DISPLAY                      Jason Handby, Adrian Howard Sep 1991
                                         Revised: Adrian Howard Nov 1992

       COPYRIGHT University of Sussex 1990. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<< DISPLAY MANAGEMENT ROUTINES >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

This REF  file details  the  procedures that  are  supplied by  the  two
library  packages  LIB * XT_DISPLAY   and  LIB * FAST_XT_DISPLAY   which
provide the Pop-11 interface to various X Toolkit Intrinsics relating to
the management of displays.

         CONTENTS - (Use <ENTER> g to access required sections)

  1   Introduction

  2   LIB XT_DISPLAY

  3   LIB FAST_XT_DISPLAY



---------------
1  Introduction
---------------

Before an application can do anything it must establish a connection  to
a server. The application does this  by opening a display and adding  it
to its  application  context.  A single  application  context  can  have
multiple displays, but a single display cannot be used by more than  one
application context  (ie,  a single  application  can talk  to  multiple
servers, but different application contexts  cannot use the same  server
connection).

Displays are  specified by  strings. A  display string  is of  the  form
'HOST:SERVER.SCREEN'.

    HOST
        refers to the name of the machine running the server.

    SERVER
        is the  server number  on that  machine. This  represents  which
        keyboard-mouse-monitor triple  to use  on the  host running  the
        server. Since most machines only  have a single keyboard,  mouse
        and monitor this number is usually zero.

    SCREEN
        specifies  the  default  screen  that  should  be  used  by  the
        application.

The '.SCREEN' part of a display string is optional, so both 'aurora:0.0'
and 'aurora:0' are legal display strings.

The library LIB * XT_DISPLAY provides the Pop-11 interface to  various X
Toolkit Intrinsics relating to the  management of displays. The  library
LIB * FAST_XT_DISPLAY   (loaded   automatically   by   LIB * XT_DISPLAY)
provides the non-type checking interface to the same procedures. The use
of these  libraries can  often  be avoided  by  using the  higher  level
procedures,    eg    XtAppInitialize    and    XtVaAppInitialize    (see
REF * XT_APPINIT).

LIB * XT_DISPLAY and LIB * FAST_XT_DISPLAY allow the following functions
to be performed:

   #  The opening and initialisation of a display.
   #  The addition of a display to an application context.
   #  Closing of a display and its removal from an application context.
   #  Finding the display associated with a widget.
   #  Finding the application context associated with a display.
   #  Importing an external display object into Pop-11.
   #  Accessing a Pop-11 device referring to a given display.

More information  on the  types of  the arguments  and results  for  the
following procedures can be found in REF * XPT_TYPES.

For more details about opening display connections see section 2.1 of:

               X Toolkit Intrinsics - C Language Interface
                       MIT X Consortium Standard,
                         X Version 11, Release 4

        Copyright (C) 1985, 1986, 1987, 1988, 1989 Massachusetts
        Institute of Technology,  Cambridge, Massachusetts,  and
        Digital Equipment Corporation, Maynard, Massachusetts.




-----------------
2  LIB XT_DISPLAY
-----------------

XtDisplayInitialize(appcontext, displayptr,                  [procedure]
                    app_name, app_class,
                    optiondesclist, num_options,
                    argc_io, argv_io)
        This  procedure  initialises  a  display  and  adds  it  to   an
        application context.  This procedure  does not  actually  open a
        display (most  application will  want  to use  XtOpenDisplay  or
        XtAppInitialize  instead).   XtDisplayInitialize  performs   the
        following operations:

          o It initialises the display and adds it to the given
            application context

          o It fetches the language string that is to be used for the
            specified display (see REF * XT_UTIL/XtResolvePathname).

          o It builds the resource database, parsing any supplied
            command line options (see REF * XT_RESOURCE).

        displayptr is  an XptDisplayPtr  to the  display that  is to  be
        added to  the application  context appcontext.  Remember  that a
        display can be in only one application context at a time.

        app_name and app_class are strings that specify the instance and
        class names of the application.

        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.

        If the boolean resource 'synchronous' is true ('+synchronous' in
        argv_io) then the display connection is placed into  synchronous
        mode by XtDisplayInitialize,  ie requests to  the server are  no
        longer buffered and are acted upon immediately. This can be very
        useful when debugging applications since errors will be reported
        when they  occur.  It  will,  however,  slow  program  execution
        considerably.

        If  the  boolean  resource  'reverseVideo'  is  true  ('+rv'  in
        argv_io) then the intrinsics exchange 'XtDefaultForeground'  and
        'XtDefaultBackground' for widgets created on this display.

        After   the   call    to   XtDisplayInitialize   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  XtDisplayInitialize  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.


XtOpenDisplay(appcontext, display,                           [procedure]
              app_name, app_class,
              optiondesclist, num_options,
              argc_io, argv_io) -> displayptr
        This procedure  opens a  display and  add it  to an  application
        context,  returning  an  XptDisplayPtr  displayptr  to  the  new
        display.

        If display is a display string,  an attempt is made to open  the
        display it  specifies. If  display is  false then  XtOpenDisplay
        uses the value of any '-display' command line option in argv_io.
        If no such command  line option exists,  then the users  default
        display is used. On Unix systems the default display will be the
        value of the display environment variable.

        After  the  display  has   been  opened,  the  procedure   calls
        XtDisplayInitialize with  the  new  display  and  the  specified
        appcontext, app_class, optiondesclist, num_options, argc_io, and
        argv_io (which are as for XtDisplayInitialize).

        The application name  passed to XtDisplayInitialize  will be  as
        follows:

          o If a '-name' command line option was specified in argv_io,
            then then its value will be passed.

          o If there was no such command line option, and app_name is a
            string, then app_name will be passed.

          o If app_name is false then the value of the Unix
            environment variable RESOURCE_NAME will be passed.

          o If RESOURCE_NAME is not set, then the name used to invoke
            the program will be used (on Unix systems this will be the
            first element of argv_io, stripped of any directory and
            file-type components).

          o If the name used to invoke the program cannot be found (eg,
            the first element of argv_io does not exist, or is an empty
            string), then the application name 'main' is passed.

        After the call to XtOpenDisplay the variable  XptUnprocessedArgs
        will contain a list of any command line arguments that were  not
        successfully parsed. See XtDisplayInitialize on how this  should
        be handled.

        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.


XtDisplay(widget) -> displayptr                              [procedure]
        Returns a  pointer to  the display  associated with  the  widget
        widget. Also see XtDisplayOfObject and XtScreen.


XtDisplayToApplicationContext(displayptr) -> appcontext      [procedure]
        Return the application  context descriptor  associated with  the
        given display. This procedure will give an error if the  display
        does not have an associated application context.


XtCloseDisplay(displayptr)                                   [procedure]
        This procedure closes the specified display and removes it  from
        its application context  (if any). If  this procedure is  called
        from some form of external callback (see REF * XT_CALLBACK)  the
        display is not  closed until  the callback  has been  completed.
        This  procedure  is  the  default  destroy  action  for  display
        descriptors.

        All the  widgets  associated  with  the  specified  display  are
        destroyed  with  fast_XtDestroyWidget  before  the  display   is
        closed.

        This procedure need only be  called if the application is  going
        to continue executing, otherwise XtDestroyApplicationContext can
        be used.




----------------------
3  LIB FAST_XT_DISPLAY
----------------------

fast_XtDisplayInitialize(appcontext, displayptr,             [procedure]
                         app_name, app_class,
                         optiondesclist, num_options,
                         argc_io, argv_io)
fast_XtOpenDisplay(appcontext, display,                      [procedure]
                   app_name, app_class,
                   optiondesclist, num_options,
                   argc_io, argv_io) -> displayptr
fast_XtDisplay(widget) -> displayptr                         [procedure]
fast_XtDisplayToApplicationContext(displayptr) -> appcontext [procedure]
fast_XtCloseDisplay(displayptr)                              [procedure]
        As for the  procedures in LIB * XT_DISPLAY,  but without  checks
        for valid arguments.  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.


XptImportDisplayPtr(exptrclass) -> displayptr or false       [procedure]
false or displayptr -> XptImportDisplayPtr() -> exptrclass
        Given an external pointer class  record pointing to an  external
        display structure, return the displayptr record for it (creating
        a new one if  necessary). If exptrclass is  a null pointer  then
        false is returned.

        If exptrclass refers to a display, it must be one that has  been
        registered with  the  toolkit, ie  one  that has  an  associated
        application context.

        If the updater is given false  it coerces it to a null  external
        pointer. If  it is  given a  displayptr it  returns an  external
        pointer class record  that refers  to the  display. NOTE:  Since
        displayptr is an external pointer class record, the updater acts
        like identfn when given a non-false value.

        This routine can  be used as  a conversion procedure  in a  type
        specification (see REF * DEFCLASS).


XptImportUnregisteredDisplayPtr(exptrclass)                  [procedure]
                -> displayptr or false
false or displayptr -> XptImportUnregisteredDisplayPtr() -> exptrclass
        Arguments and  results are  as for  XptImportDisplayPtr,  except
        that exptrclass refers to  a display pointer  that has NOT  been
        registered with the toolkit (ie, it does not have an  associated
        application context).



--- C.x/x/pop/ref/xt_display
--- Copyright University of Sussex 1991. All rights reserved.
