occt/src/BRepBuilderAPI/BRepBuilderAPI_MakePolygon.cdl

-- Created on: 1993-07-29
-- Created by: Remi LEQUETTE
-- Copyright (c) 1993-1999 Matra Datavision
-- Copyright (c) 1999-2014 OPEN CASCADE SAS
--
-- This file is part of Open CASCADE Technology software library.
--
-- This library is free software; you can redistribute it and/or modify it under
-- the terms of the GNU Lesser General Public License version 2.1 as published
-- by the Free Software Foundation, with special exception defined in the file
-- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
-- distribution for complete text of the license and disclaimer of any warranty.
--
-- Alternatively, this file may be used under the terms of Open CASCADE
-- commercial license or contractual agreement.

class MakePolygon from BRepBuilderAPI  inherits MakeShape from BRepBuilderAPI 

	---Purpose: Describes functions to build polygonal wires. A
    	-- polygonal wire can be built from any number of points
    	-- or vertices, and consists of a sequence of connected
    	-- rectilinear edges.
	--          When a point or vertex is added to the  polygon if
	--          it is identic  to the previous  point no  edge  is
	--          built. The method added can be used to test it.
    	-- Construction of a Polygonal Wire
    	-- You can construct:
    	--   -   a complete polygonal wire by defining all its points
    	--   or vertices (limited to four), or
 	-- -   an empty polygonal wire and add its points or
    	--   vertices in sequence (unlimited number).
    	-- A MakePolygon object provides a framework for:
    	-- -   initializing the construction of a polygonal wire,
    	-- -   adding points or vertices to the polygonal wire under construction, and
    	-- -   consulting the result.
        
uses
    Wire        from TopoDS,
    Edge        from TopoDS,
    Vertex      from TopoDS,
    Pnt         from gp,
    MakePolygon from BRepLib

raises
    NotDone           from StdFail

is
    Create 
    returns MakePolygon from BRepBuilderAPI;
	---Purpose: Initializes an empty polygonal wire, to which points or
    	-- vertices are added using the Add function.
    	-- As soon as the polygonal wire under construction
    	-- contains vertices, it can be consulted using the Wire function.
	
    Create(P1, P2 : Pnt from gp)
	---Level: Public
    returns MakePolygon from BRepBuilderAPI;

    Create(P1, P2, P3 : Pnt from gp; 
           Close : Boolean = Standard_False)
	---Level: Public
    returns MakePolygon from BRepBuilderAPI;

    Create(P1, P2, P3, P4 : Pnt from gp; 
           Close : Boolean = Standard_False)
	---Level: Public
    returns MakePolygon from BRepBuilderAPI;
    	---Purpose: Constructs a polygonal wire from 2, 3 or 4 points. Vertices are
    	-- automatically created on the given points. The polygonal wire is
    	-- closed if Close is true; otherwise it is open. Further vertices can
    	-- be added using the Add function. The polygonal wire under
    	-- construction can be consulted at any time by using the Wire function.
    	-- Example
    	-- //an open polygon from four points
    	-- TopoDS_Wire W = BRepBuilderAPI_MakePolygon(P1,P2,P3,P4);
    	-- Warning: The process is equivalent to:
    	--   - initializing an empty polygonal wire,
    	--   - and adding the given points in sequence.
    	-- Consequently, be careful when using this function: if the
    	-- sequence of points p1 - p2 - p1 is found among the arguments of the
    	-- constructor, you will create a polygonal wire with two
    	-- consecutive coincident edges.
        
    Create(V1, V2 : Vertex from TopoDS)
	---Level: Public
    returns MakePolygon from BRepBuilderAPI;

    Create(V1, V2, V3 : Vertex from TopoDS; 
    	   Close : Boolean = Standard_False)
	---Level: Public
    returns MakePolygon from BRepBuilderAPI;

    Create(V1, V2, V3, V4 : Vertex from TopoDS; 
           Close : Boolean = Standard_False)
	---Level: Public
    returns MakePolygon from BRepBuilderAPI;
    	---Purpose: Constructs a polygonal wire from
    	-- 2, 3 or 4 vertices. The polygonal wire is closed if Close is true;
    	-- otherwise it is open (default value). Further vertices can be
    	-- added using the Add function. The polygonal wire under
    	-- construction can be consulted at any time by using the Wire function.
    	-- Example
    	-- //a closed triangle from three vertices
    	-- TopoDS_Wire W = BRepBuilderAPI_MakePolygon(V1,V2,V3,Standard_True);
    	-- Warning
    	-- The process is equivalent to:
    	-- -      initializing an empty polygonal wire,
    	-- -      then adding the given points in sequence.
    	-- So be careful, as when using this function, you could create a
    	-- polygonal wire with two consecutive coincident edges if
    	-- the sequence of vertices v1 - v2 - v1 is found among the
    	-- constructor's arguments.
    	
    Add(me : in out; P : Pnt from gp)
	---Level: Public
    is static;

    Add(me : in out; V : Vertex from TopoDS)
	---Level: Public
    is static;
    	--- Purpose:
    	-- Adds the point P or the vertex V at the end of the
    	-- polygonal wire under construction. A vertex is
    	-- automatically created on the point P.
    	-- Warning
    	-- -   When P or V is coincident to the previous vertex,
    	--   no edge is built. The method Added can be used to
    	--   test for this. Neither P nor V is checked to verify
    	--   that it is coincident with another vertex than the last
    	--   one, of the polygonal wire under construction. It is
    	--   also possible to add vertices on a closed polygon
    	--   (built for example by using a constructor which
    	--   declares the polygon closed, or after the use of the Close function).
    	--  Consequently, be careful using this function: you might create:
    	-- -      a polygonal wire with two consecutive coincident edges, or
    	-- -      a non manifold polygonal wire.
    	-- -      P or V is not checked to verify if it is
    	--    coincident with another vertex but the last one, of
    	--    the polygonal wire under construction. It is also
    	--    possible to add vertices on a closed polygon (built
    	--    for example by using a constructor which declares
    	--    the polygon closed, or after the use of the Close function).
    	-- Consequently, be careful when using this function: you might create:
    	--   -   a polygonal wire with two consecutive coincident edges, or
    	--   -   a non-manifold polygonal wire.
        
    Added(me) returns Boolean
	---Purpose: Returns true if the last vertex added to the constructed
    	-- polygonal wire is not coincident with the previous one.
    is static;
    
    Close(me : in out)
	---Purpose: Closes the polygonal wire under construction. Note - this
    	-- is equivalent to adding the first vertex to the polygonal
    	-- wire under construction.
    is static;
    
    FirstVertex(me) returns Vertex from TopoDS
	---C++: return const &
	---Level: Public
    is static;

    LastVertex(me) returns Vertex from TopoDS
	---C++: return const &
	---Level: Public
    is static;
    	---Purpose: Returns the first or the last vertex of the polygonal wire under construction.
    	-- If the constructed polygonal wire is closed, the first and the last vertices are identical.   

    IsDone(me) returns Boolean
	---Level: Public
    is redefined;
    	---Purpose:
    	-- Returns true if this algorithm contains a valid polygonal
    	-- wire (i.e. if there is at least one edge).
    	-- IsDone returns false if fewer than two vertices have
    	-- been chained together by this construction algorithm.
        
    Edge(me) returns Edge from TopoDS
	---Purpose: Returns the edge built between the last two points or
    	-- vertices added to the constructed polygonal wire under construction.
    	-- Warning
    	-- If there is only one vertex in the polygonal wire, the result is a null edge.
    	---C++: return const &
	---C++: alias "Standard_EXPORT operator TopoDS_Edge() const;"
  raises
    	NotDone from StdFail
    is static;

    Wire(me) returns Wire from TopoDS
	---Purpose:
    	-- Returns the constructed polygonal wire, or the already
    	-- built part of the polygonal wire under construction.
    	-- Exceptions
    	-- StdFail_NotDone if the wire is not built, i.e. if fewer than
    	-- two vertices have been chained together by this construction algorithm.
    	---C++: return const &
	---C++: alias "Standard_EXPORT operator TopoDS_Wire() const;"
  raises
    	NotDone from StdFail
    is static;

fields

    myMakePolygon : MakePolygon from BRepLib;
    
end MakePolygon;