libwindows(S)                  6 January 1993                  libwindows(S)


 Name

    libwindows - windowing terminal function library

 Syntax


    cc  . . .  -lwindows


    int openagent()

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

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

    int openchan (chan)
    int chan;

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

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

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

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

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

    int Move (cntlfd, chan, origin_x, origin_y)
    int cntfld, chan, origin_x, origin_y;

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

    int Exit (cntlfd)
    int cntlfd;


 Description

    This library of routines enables a program running on a host system to
    perform windowing terminal functions (see layers(C)).

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

    The New routine creates a new layer with a separate shell.  The
    originx, originy, cornerx, and cornery 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 (that is,
    the keyboard is not attached to the new layer).  Upon successful comple-
    tion, New returns the xt(HW) channel number associated with the layer.
    Otherwise, the value -1 is returned.

    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 successful completion, openchan
    returns a file descriptor that can be used as input to write(S) or
    close(S).  Otherwise, the value -1 is returned.

    The Runlayer routine runs the specified command in the layer associated
    with the channel argument chan.  Any processes currently attached to this
    layer is killed, and the new process has the environment of the layers(C)
    process.

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

    The Delete routine deletes the layer associated with the channel argument
    chan and kills all host processes associated 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 channel 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 (originx, originy).  The size and contents of the layer
    are maintained.

    The Reshape routine reshapes the layer associated with the channel argu-
    ment chan.  The arguments originx, originy, cornerx, and cornery are
    the new coordinates of the layer rectangle.  If all the coordinate argu-
    ments are 0, the user is allowed to define the layer's rectangle interac-
    tively.

    The Exit routine causes the layers(C) program to exit, killing all pro-
    cesses associated with it.

 Return value

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

 Files

    /usr/lib/libwindows.a   windowing terminal function library

 Note

    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 expects
    these numbers to be passed as character positions (bytes); others expects
    the information to be in pixels (bits).

    For example, for the AT&T TELETYPE 5620 DMD terminal, New, Newlayer, and
    Reshape take minimum values of 8 (pixels) for originx and originy and
    maximum values of 792 (pixels) for cornerx and 1016 (pixels) for
    cornery.  In addition, the minimum layer size is 28 by 28 pixels and the
    maximum layer size is 784 by 1008 pixels.

 See also

    close(S), jagent(M), write(S), layers(C), xt(HW).

 Standards conformance

    libwindows is not part of any currently supported standard; it is an
    extension of AT&T System V provided by the Santa Cruz Operation.