0023024: Update headers of OCCT files

[occt.git] / src / BRepBuilderAPI / BRepBuilderAPI_MakeWire.cdl

-- Created on: 1993-07-08
-- Created by: Remi LEQUETTE
-- Copyright (c) 1993-1999 Matra Datavision
-- Copyright (c) 1999-2012 OPEN CASCADE SAS
--
-- The content of this file is subject to the Open CASCADE Technology Public
-- License Version 6.5 (the "License"). You may not use the content of this file
-- except in compliance with the License. Please obtain a copy of the License
-- at http://www.opencascade.org and read it completely before using this file.
--
-- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
-- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
--
-- The Original Code and all software distributed under the License is
-- distributed on an "AS IS" basis, without warranty of any kind, and the
-- Initial Developer hereby disclaims all such warranties, including without
-- limitation, any warranties of merchantability, fitness for a particular
-- purpose or non-infringement. Please see the License for the specific terms
-- and conditions governing the rights and limitations under the License.




class MakeWire from BRepBuilderAPI inherits MakeShape from BRepBuilderAPI 

	---Purpose: Describes functions to build wires from edges. A wire can
    	-- be built from any number of edges.
    	-- To build a wire you first initialize the construction, then
    	-- add edges in sequence. An unlimited number of edges
    	-- can be added. The initialization of construction is done with:
    	-- -   no edge (an empty wire), or
    	-- -   edges of an existing wire, or
    	-- -   up to four connectable edges.
    	-- In order to be added to a wire under construction, an
    	-- edge (unless it is the first one) must satisfy the following
    	-- condition: one of its vertices must be geometrically
    	-- coincident with one of the vertices of the wire (provided
    	-- that the highest tolerance factor is assigned to the two
    	-- vertices). It could also be the same vertex.
    	-- -   The given edge is shared by the wire if it contains:
    	--   -   two vertices, identical to two vertices of the wire
    	--    under construction (a general case of the wire closure), or
    	--   -   one vertex, identical to a vertex of the wire under
    	--    construction; the other vertex not being
    	--    geometrically coincident with another vertex of the wire.
    	-- -   In other cases, when one of the vertices of the edge
    	--   is simply geometrically coincident with a vertex of the
    	--   wire under construction (provided that the highest
    	--   tolerance factor is assigned to the two vertices), the
    	--   given edge is first copied and the coincident vertex is
    	-- replaced in this new edge, by the coincident vertex of the wire.
    	--  Note: it is possible to build non manifold wires using this construction tool.
    	-- A MakeWire object provides a framework for:
    	-- -   initializing the construction of a wire,
    	-- -   adding edges to the wire under construction, and
    	-- -   consulting the result.

uses
    Vertex      from TopoDS,
    Edge        from TopoDS,
    Wire        from TopoDS,
    ListOfShape from TopTools,
    WireError   from BRepBuilderAPI,
    MakeWire    from BRepLib

raises
    NotDone    from StdFail

is

    Create                                              
	---Purpose: Constructs an empty wire framework, to which edges
    	-- are added using the Add function.
    	-- As soon as the wire contains one edge, it can return
    	-- with the use of the function Wire.
    	-- Warning
    	-- The function Error will return
    	-- BRepBuilderAPI_EmptyWire if it is called before at
    	-- least one edge is added to the wire under construction.
    returns MakeWire from BRepBuilderAPI;
    
    ----------------------------------------------
    -- From edges
    ----------------------------------------------

    Create(E : Edge from TopoDS)                        
	---Purpose: Make a Wire from an edge.
	---Level: Public
    returns MakeWire from BRepBuilderAPI;

    Create(E1,E2 : Edge from TopoDS)                    
	---Purpose: Make a Wire from two edges.
	---Level: Public
    returns MakeWire from BRepBuilderAPI;

    Create(E1,E2,E3 : Edge from TopoDS)                 
	---Purpose: Make a Wire from three edges.
	---Level: Public
    returns MakeWire from BRepBuilderAPI;

    Create(E1,E2,E3,E4 : Edge from TopoDS)              
	---Purpose: Make a Wire from four edges.
	---Level: Public
    returns MakeWire from BRepBuilderAPI;
    	---Purpose: Constructs a wire
    	-- -   from the TopoDS_Wire W composed of the edge E, or
    	-- -   from edge E, or
    	-- -   from two edges E1 and E2, or
    	-- -   from three edges E1, E2 and E3, or
    	-- -   from four edges E1, E2, E3 and E4.
    	-- Further edges can be added using the function Add.
    	-- Given edges are added in a sequence. Each of them
    	-- must be connectable to the wire under construction,
    	-- and so must satisfy the following condition (unless it is
    	-- the first edge of the wire): one of its vertices must be
    	-- geometrically coincident with one of the vertices of the
    	-- wire (provided that the highest tolerance factor is
    	-- assigned to the two vertices). It could also be the same vertex.
    	-- Warning
    	-- If an edge is not connectable to the wire under
    	-- construction it is not added. The function Error will
    	-- return BRepBuilderAPI_DisconnectedWire, the
    	-- function IsDone will return false and the function Wire
    	-- will raise an error, until a new connectable edge is added.  
	
    ----------------------------------------------
    -- From wire and edge
    ----------------------------------------------

    Create(W : Wire from TopoDS)                        
	---Purpose: Make a Wire from a Wire. Usefull for adding later.
	---Level: Public
    returns MakeWire from BRepBuilderAPI;

    Create(W : Wire from TopoDS; E : Edge from TopoDS)  
	---Purpose: Add an edge to a wire.
	---Level: Public
    returns MakeWire from BRepBuilderAPI;
	
    ----------------------------------------------
    -- Auxiliary methods
    ----------------------------------------------

    Add(me : in out; E : Edge from TopoDS)
	---Purpose:  Adds the edge E to the wire under construction.
    	-- E must be connectable to the wire under construction, and, unless it
    	-- is the first edge of the wire, must satisfy the following
    	-- condition: one of its vertices must be geometrically coincident
    	-- with one of the vertices of the wire (provided that the highest
    	-- tolerance factor is assigned to the two vertices). It could also
    	-- be the same vertex.
    	-- Warning
    	-- If E is not connectable to the wire under construction it is not
    	-- added. The function Error will return
    	-- BRepBuilderAPI_DisconnectedWire, the function IsDone will return
    	-- false and the function Wire will raise an error, until a new
    	-- connectable edge is added.
    is static;
    
    Add(me : in out; W : Wire from TopoDS)
	---Purpose: Add the edges of <W> to the current wire.
	---Level: Public
    is static;
    
    Add(me : in out; L : ListOfShape from TopTools)
	---Purpose: Adds  the edges of <L>   to the current  wire.  The
	--          edges are not to be consecutive.   But they are to
	--          be  all  connected geometrically or topologically.
	--          If some of them are  not connected the Status give
	--          DisconnectedWire but the "Maker" is Done() and you
	--          can get the  partial result. (ie connected to  the
	--          first edgeof the list <L>)
        is static;
    
    ----------------------------------------------
    -- Results
    ----------------------------------------------

    IsDone(me) returns Boolean
	---Purpose: Returns true if this algorithm contains a valid wire.
    	-- IsDone returns false if:
    	-- -   there are no edges in the wire, or
    	-- -   the last edge which you tried to add was not connectable.
    is redefined;

    Error(me) returns WireError from BRepBuilderAPI
	---Purpose: Returns the construction status
    	-- -   BRepBuilderAPI_WireDone if the wire is built, or
    	-- -   another value of the BRepBuilderAPI_WireError
    	--   enumeration indicating why the construction failed.
    is static;

    Wire(me) returns Wire from TopoDS
	---Purpose: Returns the constructed wire; or the part of the wire
    	-- under construction already built.
    	-- Exceptions StdFail_NotDone if a wire is not built.
    	---C++: return const &
    	---C++: alias "Standard_EXPORT operator TopoDS_Wire() const;"
	 raises
    	NotDone from StdFail
    is static;
    
    Edge(me) returns Edge from TopoDS
	---C++: return const &
    	---Purpose: Returns the last edge added to the wire under construction.
    	-- Warning
    	-- -   This edge can be different from the original one (the
    	--   argument of the function Add, for instance,)
    	-- -   A null edge is returned if there are no edges in the
    	--   wire under construction, or if the last edge which you
    	--   tried to add was not connectable..
	    raises
    	NotDone from StdFail
    is static;
    
    Vertex(me) returns Vertex from TopoDS
	---C++: return const &
    	---Purpose: Returns the last vertex of the last edge added to the
    	-- wire under construction.
    	-- Warning
    	-- A null vertex is returned if there are no edges in the wire
    	-- under construction, or if the last edge which you tried to
    	-- add was not connectableR
    raises
    	NotDone from StdFail
    is static;
     

fields
    myMakeWire : MakeWire from BRepLib;

end MakeWire;