0024624: Lost word in license statement in source files
[occt.git] / src / BRepBuilderAPI / BRepBuilderAPI_MakeWire.cdl
1 -- Created on: 1993-07-08
2 -- Created by: Remi LEQUETTE
3 -- Copyright (c) 1993-1999 Matra Datavision
4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
5 --
6 -- This file is part of Open CASCADE Technology software library.
7 --
8 -- This library is free software; you can redistribute it and/or modify it under
9 -- the terms of the GNU Lesser General Public License version 2.1 as published
10 -- by the Free Software Foundation, with special exception defined in the file
11 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
12 -- distribution for complete text of the license and disclaimer of any warranty.
13 --
14 -- Alternatively, this file may be used under the terms of Open CASCADE
15 -- commercial license or contractual agreement.
16
17 class MakeWire from BRepBuilderAPI inherits MakeShape from BRepBuilderAPI 
18
19         ---Purpose: Describes functions to build wires from edges. A wire can
20         -- be built from any number of edges.
21         -- To build a wire you first initialize the construction, then
22         -- add edges in sequence. An unlimited number of edges
23         -- can be added. The initialization of construction is done with:
24         -- -   no edge (an empty wire), or
25         -- -   edges of an existing wire, or
26         -- -   up to four connectable edges.
27         -- In order to be added to a wire under construction, an
28         -- edge (unless it is the first one) must satisfy the following
29         -- condition: one of its vertices must be geometrically
30         -- coincident with one of the vertices of the wire (provided
31         -- that the highest tolerance factor is assigned to the two
32         -- vertices). It could also be the same vertex.
33         -- -   The given edge is shared by the wire if it contains:
34         --   -   two vertices, identical to two vertices of the wire
35         --    under construction (a general case of the wire closure), or
36         --   -   one vertex, identical to a vertex of the wire under
37         --    construction; the other vertex not being
38         --    geometrically coincident with another vertex of the wire.
39         -- -   In other cases, when one of the vertices of the edge
40         --   is simply geometrically coincident with a vertex of the
41         --   wire under construction (provided that the highest
42         --   tolerance factor is assigned to the two vertices), the
43         --   given edge is first copied and the coincident vertex is
44         -- replaced in this new edge, by the coincident vertex of the wire.
45         --  Note: it is possible to build non manifold wires using this construction tool.
46         -- A MakeWire object provides a framework for:
47         -- -   initializing the construction of a wire,
48         -- -   adding edges to the wire under construction, and
49         -- -   consulting the result.
50
51 uses
52     Vertex      from TopoDS,
53     Edge        from TopoDS,
54     Wire        from TopoDS,
55     ListOfShape from TopTools,
56     WireError   from BRepBuilderAPI,
57     MakeWire    from BRepLib
58
59 raises
60     NotDone    from StdFail
61
62 is
63
64     Create                                              
65         ---Purpose: Constructs an empty wire framework, to which edges
66         -- are added using the Add function.
67         -- As soon as the wire contains one edge, it can return
68         -- with the use of the function Wire.
69         -- Warning
70         -- The function Error will return
71         -- BRepBuilderAPI_EmptyWire if it is called before at
72         -- least one edge is added to the wire under construction.
73     returns MakeWire from BRepBuilderAPI;
74     
75     ----------------------------------------------
76     -- From edges
77     ----------------------------------------------
78
79     Create(E : Edge from TopoDS)                        
80         ---Purpose: Make a Wire from an edge.
81         ---Level: Public
82     returns MakeWire from BRepBuilderAPI;
83
84     Create(E1,E2 : Edge from TopoDS)                    
85         ---Purpose: Make a Wire from two edges.
86         ---Level: Public
87     returns MakeWire from BRepBuilderAPI;
88
89     Create(E1,E2,E3 : Edge from TopoDS)                 
90         ---Purpose: Make a Wire from three edges.
91         ---Level: Public
92     returns MakeWire from BRepBuilderAPI;
93
94     Create(E1,E2,E3,E4 : Edge from TopoDS)              
95         ---Purpose: Make a Wire from four edges.
96         ---Level: Public
97     returns MakeWire from BRepBuilderAPI;
98         ---Purpose: Constructs a wire
99         -- -   from the TopoDS_Wire W composed of the edge E, or
100         -- -   from edge E, or
101         -- -   from two edges E1 and E2, or
102         -- -   from three edges E1, E2 and E3, or
103         -- -   from four edges E1, E2, E3 and E4.
104         -- Further edges can be added using the function Add.
105         -- Given edges are added in a sequence. Each of them
106         -- must be connectable to the wire under construction,
107         -- and so must satisfy the following condition (unless it is
108         -- the first edge of the wire): one of its vertices must be
109         -- geometrically coincident with one of the vertices of the
110         -- wire (provided that the highest tolerance factor is
111         -- assigned to the two vertices). It could also be the same vertex.
112         -- Warning
113         -- If an edge is not connectable to the wire under
114         -- construction it is not added. The function Error will
115         -- return BRepBuilderAPI_DisconnectedWire, the
116         -- function IsDone will return false and the function Wire
117         -- will raise an error, until a new connectable edge is added.  
118         
119     ----------------------------------------------
120     -- From wire and edge
121     ----------------------------------------------
122
123     Create(W : Wire from TopoDS)                        
124         ---Purpose: Make a Wire from a Wire. Usefull for adding later.
125         ---Level: Public
126     returns MakeWire from BRepBuilderAPI;
127
128     Create(W : Wire from TopoDS; E : Edge from TopoDS)  
129         ---Purpose: Add an edge to a wire.
130         ---Level: Public
131     returns MakeWire from BRepBuilderAPI;
132         
133     ----------------------------------------------
134     -- Auxiliary methods
135     ----------------------------------------------
136
137     Add(me : in out; E : Edge from TopoDS)
138         ---Purpose:  Adds the edge E to the wire under construction.
139         -- E must be connectable to the wire under construction, and, unless it
140         -- is the first edge of the wire, must satisfy the following
141         -- condition: one of its vertices must be geometrically coincident
142         -- with one of the vertices of the wire (provided that the highest
143         -- tolerance factor is assigned to the two vertices). It could also
144         -- be the same vertex.
145         -- Warning
146         -- If E is not connectable to the wire under construction it is not
147         -- added. The function Error will return
148         -- BRepBuilderAPI_DisconnectedWire, the function IsDone will return
149         -- false and the function Wire will raise an error, until a new
150         -- connectable edge is added.
151     is static;
152     
153     Add(me : in out; W : Wire from TopoDS)
154         ---Purpose: Add the edges of <W> to the current wire.
155         ---Level: Public
156     is static;
157     
158     Add(me : in out; L : ListOfShape from TopTools)
159         ---Purpose: Adds  the edges of <L>   to the current  wire.  The
160         --          edges are not to be consecutive.   But they are to
161         --          be  all  connected geometrically or topologically.
162         --          If some of them are  not connected the Status give
163         --          DisconnectedWire but the "Maker" is Done() and you
164         --          can get the  partial result. (ie connected to  the
165         --          first edgeof the list <L>)
166         is static;
167     
168     ----------------------------------------------
169     -- Results
170     ----------------------------------------------
171
172     IsDone(me) returns Boolean
173         ---Purpose: Returns true if this algorithm contains a valid wire.
174         -- IsDone returns false if:
175         -- -   there are no edges in the wire, or
176         -- -   the last edge which you tried to add was not connectable.
177     is redefined;
178
179     Error(me) returns WireError from BRepBuilderAPI
180         ---Purpose: Returns the construction status
181         -- -   BRepBuilderAPI_WireDone if the wire is built, or
182         -- -   another value of the BRepBuilderAPI_WireError
183         --   enumeration indicating why the construction failed.
184     is static;
185
186     Wire(me) returns Wire from TopoDS
187         ---Purpose: Returns the constructed wire; or the part of the wire
188         -- under construction already built.
189         -- Exceptions StdFail_NotDone if a wire is not built.
190         ---C++: return const &
191         ---C++: alias "Standard_EXPORT operator TopoDS_Wire() const;"
192          raises
193         NotDone from StdFail
194     is static;
195     
196     Edge(me) returns Edge from TopoDS
197         ---C++: return const &
198         ---Purpose: Returns the last edge added to the wire under construction.
199         -- Warning
200         -- -   This edge can be different from the original one (the
201         --   argument of the function Add, for instance,)
202         -- -   A null edge is returned if there are no edges in the
203         --   wire under construction, or if the last edge which you
204         --   tried to add was not connectable..
205             raises
206         NotDone from StdFail
207     is static;
208     
209     Vertex(me) returns Vertex from TopoDS
210         ---C++: return const &
211         ---Purpose: Returns the last vertex of the last edge added to the
212         -- wire under construction.
213         -- Warning
214         -- A null vertex is returned if there are no edges in the wire
215         -- under construction, or if the last edge which you tried to
216         -- add was not connectableR
217     raises
218         NotDone from StdFail
219     is static;
220      
221
222 fields
223     myMakeWire : MakeWire from BRepLib;
224
225 end MakeWire;