libwindows(3X)   MISCELLANEOUS LIBRARY FUNCTIONS   libwindows(3X)



NAME
     libwindows - windowing terminal function library

SYNOPSIS
     cc [flag ...] file ...  -lwindows [library ...]

     int openagent (void);

     int New (int cntlfd, int origin_x, int origin_y,
       int corner_x, int corner_y);
     int Newlayer (int cntlfd, int origin_x, int origin_y,
       int corner_x, int corner_y);

     int openchan (int chan);
     int Runlayer (int chan, char *command);

     int Current (int cntlfd, int chan);
     int Delete (int cntlfd, int chan);

     int Top (int cntlfd, int chan);
     int Bottom (int cntlfd, int chan);

     int Move (int cntlfd, int chan, int origin_x, int origin_y);
     int Reshape (int cntlfd, int chan, int origin_x, int origin_y,
       int corner_x, int corner_y);

     int Exit (int cntlfd);

DESCRIPTION
     This library of routines enables a program running on a host
     UNIX  system  to  perform  windowing terminal functions [see
     layers(1)].

     The openagent routine opens the control channel of the xt(7)
     channel  group  to  which the calling process belongs.  Upon
     successful completion, openagent returns a  file  descriptor
     that  can  be passed to any of the other libwindows routines
     except openchan and Runlayer.  (The file descriptor can also
     be  passed  to the close system call.)  Otherwise, the value
     -1 is returned.

     The New routine creates a new layer with a  separate  shell.
     The   origin_x,  origin_y,  corner_x, and corner_y arguments
     are the coordinates of the  layer  rectangle.   If  all  the
     coordinate arguments are 0, the user must define the layer's
     rectangle interactively.  The layer appears on  top  of  any
     overlapping  layers.   The  layer is not made current (i.e.,
     the keyboard is not attached to the new layer).   Upon  suc-
     cessful  completion,  New  returns  the xt(7) channel number
     associated with the  layer.   Otherwise,  the  value  -1  is
     returned.




              Last change: AT&T Windowing Utilities             1

libwindows(3X)   MISCELLANEOUS LIBRARY FUNCTIONS   libwindows(3X)



     The Newlayer routine creates a new layer without executing a
     separate shell.  Otherwise it is identical to New, described
     above.

     The openchan routine opens the channel argument  chan  which
     is obtained from the New or Newlayer routine.  Upon success-
     ful completion, openchan returns a file descriptor that  can
     be  used  as  input to write(2) or close(2).  Otherwise, the
     value -1 is returned.

     The Runlayer routine runs the specified command in the layer
     associated  with  the  channel argument chan.  This layer is
     usually a  layer  previously  created  with  Newlayer.   Any
     processes  currently  attached to this layer will be killed,
     and the new process will have the environment of the  layers
     process.

     The Current routine makes  the  layer  associated  with  the
     channel  argument  chan  current (i.e., attached to the key-
     board).

     The Delete routine deletes the  layer  associated  with  the
     channel  argument  chan and kills all host processes associ-
     ated with the layer.

     The Top routine makes the layer associated with the  channel
     argument chan appear on top of all overlapping layers.

     The Bottom routine puts the layer associated with the  chan-
     nel argument chan under all overlapping layers.

     The Move routine moves the layer associated with the channel
     argument  chan  from  its  current  screen location to a new
     screen location at the origin  point  (origin_x,  origin_y).
     The size and contents of the layer are maintained.

     The Reshape routine reshapes the layer associated  with  the
     channel  argument  chan.   The arguments origin_x, origin_y,
     corner_x, and corner_y are the new coordinates of the  layer
     rectangle.   If all the coordinate arguments are 0, the user
     is allowed to define the layer's rectangle interactively.

     The Exit routine causes the layers program to exit,  killing
     all processes associated with it.

FILES
     ULIBDIR/libwindows.a   windowing terminal function library
     ULIBDIR   usually /usr/lib

SEE ALSO
     close(2), write(2), jagent(5).
     layers(1) in the User's Reference Manual.



              Last change: AT&T Windowing Utilities             2

libwindows(3X)   MISCELLANEOUS LIBRARY FUNCTIONS   libwindows(3X)



DIAGNOSTICS
     Upon successful completion, Runlayer, Current, Delete,  Top,
     Bottom,  Move,  Reshape, and Exit return 0, while openagent,
     New, Newlayer, and openchan return values as described above
     under each routine.  If an error occurs, -1 is returned.

NOTES
     The values of layer rectangle coordinates are  dependent  on
     the  type of terminal.  This dependency affects the routines
     that pass layer rectangle coordinates:  Move, New, Newlayer,
     and Reshape.  Some terminals will expect these numbers to be
     passed as character positions (bytes);  others  will  expect
     the information to be in pixels (bits).










































              Last change: AT&T Windowing Utilities             3

libwindows(3X)   MISCELLANEOUS LIBRARY FUNCTIONS   libwindows(3X)



     For example, for the AT&T 5620 DMD terminal, New,  Newlayer,
     and  Reshape  take minimum values of 8 (pixels) for origin_x
     and origin_y and maximum values of 792 (pixels) for corner_x
     and  1016  (pixels) for corner_y.  The minimum layer size is
     28 by 28 pixels and the maximum layer size is  784  by  1008
     pixels.    It   is   recommended   that   applications   use
     /dev/xt/??[0-7] instead of /dev/xt??[0-7] when accessing the
     xt driver.















































              Last change: AT&T Windowing Utilities             4