Function:     GgiViewport

Purpose:      Create a Ggi viewport element

Category:     USER-INTERFACE

File:         ggi.src

Author:       J.P. Terlouw

Use:          
              #include "ggi.h"
              ident viewport;
              char *name;
              int  width, height;

              viewport = GgiViewport(keyword, width, height);

                 viewport  -  'handle' by which the element can be referenced.
                 keyword   -  the viewport's user input keyword.
                 width     -  the viewport's horizontal size.
                 height    -  the viewport's vertical size.

Description:  GgiViewport creates a viewport element. A viewport element can
              be used as a container for any number of other Ggi elements.
              These elements are positioned relative to the viewport's left
              and top edge or relative to other elements within the same
              viewport. If the contents of a viewport do not fit in any
              dimension, scrollbars will be added to it so that the user
              can move to any part of the contents.

              If width or height is specified as zero, that dimension of the
              viewport will be just large enough to enclose its initial
              contents.

              The keyword can be used to control or inquire which part of the
              viewport's contents is shown. It represents the center of the
              displayed part in normalized coordinates from (0,0) to (1,1).
              (0,0) is the upper left and (1,1) the lower right corner.
              E.g. if the keyword would be VIEWPOS=, then specifying
              VIEWPOS= 0.5 0.5 would cause the central part of the contents to
              be displayed. After the keyword has been modified at least once,
              manipulating the viewport's scrollbars will cause the keyword
              to be updated. The keyword can then be read to obtain the current
              display position.

              If a viewport element is  deleted, all elements contained by it
              will be deleted automatically.

Related document:
              GgiUseShell.dc2

Updates:      Nov  2, 1999: JPT, Document created.
              Oct  9, 2001: JPT, Implemented keyword.