CSolver - enforces connector semantics

SYNOPSIS

       #include <Unidraw/csolver.h>

DESCRIPTION

       A CSolver object defines and implements a model for speci-
       fying connectivity semantics that connector subclasses can
       build upon to implement their specialized semantics.  Nor-
       mally, only one CSolver instance is used per  application,
       and only connector subclasses need access it.  The Unidraw
       class constructor initializes the csolver global to  point
       to  a  CSolver  instance  it  creates.   Thus applications
       should not instantiate CSolver directly.

       CSolver  models  a  connection  between   two   connectors
       (regardless  of their particular subclass or semantics) as
       a pair of generic connectors with a piece of CGlue  inter-
       posed.   The  CGlue characterizes the relationship between
       the connectors' centers in terms of a natural size  (which
       corresponds to the distance between the centers), elastic-
       ity, and deformation limits.  Connector subclasses specify
       their connectivity behavior with a CGlue instance and sub-
       sequently rely on the CSolver to reorient them to  conform
       to that behavior.  For example, when a pin is told to con-
       nect itself to another pin, it registers with  the  global
       csolver  a  connection  containing the two connectors (the
       pins themselves) and a piece of CGlue having zero  natural
       size, elasticity, and deformation limits.  This specifica-
       tion effectively constrains  the  connectors'  centers  to
       coincide.   The  connectivity semantics of other connector
       combinations, including those  involving  application-spe-
       cific connectors, must be specified using CGlue.

PUBLIC OPERATIONS

       CSolver()
              Create a new instance.  Application programs do not
              normally instantiate CSolver explicitly.

       virtual void Connect(Connector*, Connector*, CGlue* = nil)
              Specify   a   connection  between  two  connectors,
              optionally with a piece of CGlue interposed.  Omit-
              ting  the CGlue parameter is equivalent to specify-
              ing a connection with  CGlue  having  zero  natural
              size, elasticity, and deformation limits.

       void Disconnect(Connector*, Connector*)
       void Disconnect(Connector*)
              Destroy  the  connection(s) established between two
              connectors (the two-parameter form), or destroy all
              connections to a given connector (the one-parameter
              form).
              Solve instructs the CSolver to  reorient  connected
              connectors  to conform to their connectivity seman-
              tics as reflected by its connection specifications.
              Normally  this function is called automatically and
              only in response to Unidraw::Update.

       CSolverState* GetState(Connector*)
       void SetState(CSolverState*)
              CSolverState is a class that encapsulates  all  the
              information  about  the connections in which a con-
              nector participates.  Only CSolver can create or do
              anything  with  a  CSolverState  instance. GetState
              initializes and returns a CSolverState instance for
              the  given  connector, and SetState establishes the
              connections that a CSolverState instance  specifies
              without  disturbing  existing  connections.   These
              operations are  useful  when  it  is  necessary  to
              reestablish  a  connector's  connections after they
              have been lost, for example, by removing  the  con-
              nector from the component hierarchy (as caused by a
              command to delete the component).

       void Read(istream&)
       void Write(ostream&)
              Explicitly  read/write   the   csolver's   contents
              from/to  disk.  Normally only a catalog calls these
              operations.

SEE ALSO

       Catalog(3U), GGlue(3U), Connector(3U), globals(3U)