0023024: Update headers of OCCT 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-2012 OPEN CASCADE SAS
5 --
6 -- The content of this file is subject to the Open CASCADE Technology Public
7 -- License Version 6.5 (the "License"). You may not use the content of this file
8 -- except in compliance with the License. Please obtain a copy of the License
9 -- at http://www.opencascade.org and read it completely before using this file.
10 --
11 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
12 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
13 --
14 -- The Original Code and all software distributed under the License is
15 -- distributed on an "AS IS" basis, without warranty of any kind, and the
16 -- Initial Developer hereby disclaims all such warranties, including without
17 -- limitation, any warranties of merchantability, fitness for a particular
18 -- purpose or non-infringement. Please see the License for the specific terms
19 -- and conditions governing the rights and limitations under the License.
20
21
22
23
24 class MakeWire from BRepBuilderAPI inherits MakeShape from BRepBuilderAPI 
25
26         ---Purpose: Describes functions to build wires from edges. A wire can
27         -- be built from any number of edges.
28         -- To build a wire you first initialize the construction, then
29         -- add edges in sequence. An unlimited number of edges
30         -- can be added. The initialization of construction is done with:
31         -- -   no edge (an empty wire), or
32         -- -   edges of an existing wire, or
33         -- -   up to four connectable edges.
34         -- In order to be added to a wire under construction, an
35         -- edge (unless it is the first one) must satisfy the following
36         -- condition: one of its vertices must be geometrically
37         -- coincident with one of the vertices of the wire (provided
38         -- that the highest tolerance factor is assigned to the two
39         -- vertices). It could also be the same vertex.
40         -- -   The given edge is shared by the wire if it contains:
41         --   -   two vertices, identical to two vertices of the wire
42         --    under construction (a general case of the wire closure), or
43         --   -   one vertex, identical to a vertex of the wire under
44         --    construction; the other vertex not being
45         --    geometrically coincident with another vertex of the wire.
46         -- -   In other cases, when one of the vertices of the edge
47         --   is simply geometrically coincident with a vertex of the
48         --   wire under construction (provided that the highest
49         --   tolerance factor is assigned to the two vertices), the
50         --   given edge is first copied and the coincident vertex is
51         -- replaced in this new edge, by the coincident vertex of the wire.
52         --  Note: it is possible to build non manifold wires using this construction tool.
53         -- A MakeWire object provides a framework for:
54         -- -   initializing the construction of a wire,
55         -- -   adding edges to the wire under construction, and
56         -- -   consulting the result.
57
58 uses
59     Vertex      from TopoDS,
60     Edge        from TopoDS,
61     Wire        from TopoDS,
62     ListOfShape from TopTools,
63     WireError   from BRepBuilderAPI,
64     MakeWire    from BRepLib
65
66 raises
67     NotDone    from StdFail
68
69 is
70
71     Create                                              
72         ---Purpose: Constructs an empty wire framework, to which edges
73         -- are added using the Add function.
74         -- As soon as the wire contains one edge, it can return
75         -- with the use of the function Wire.
76         -- Warning
77         -- The function Error will return
78         -- BRepBuilderAPI_EmptyWire if it is called before at
79         -- least one edge is added to the wire under construction.
80     returns MakeWire from BRepBuilderAPI;
81     
82     ----------------------------------------------
83     -- From edges
84     ----------------------------------------------
85
86     Create(E : Edge from TopoDS)                        
87         ---Purpose: Make a Wire from an edge.
88         ---Level: Public
89     returns MakeWire from BRepBuilderAPI;
90
91     Create(E1,E2 : Edge from TopoDS)                    
92         ---Purpose: Make a Wire from two edges.
93         ---Level: Public
94     returns MakeWire from BRepBuilderAPI;
95
96     Create(E1,E2,E3 : Edge from TopoDS)                 
97         ---Purpose: Make a Wire from three edges.
98         ---Level: Public
99     returns MakeWire from BRepBuilderAPI;
100
101     Create(E1,E2,E3,E4 : Edge from TopoDS)              
102         ---Purpose: Make a Wire from four edges.
103         ---Level: Public
104     returns MakeWire from BRepBuilderAPI;
105         ---Purpose: Constructs a wire
106         -- -   from the TopoDS_Wire W composed of the edge E, or
107         -- -   from edge E, or
108         -- -   from two edges E1 and E2, or
109         -- -   from three edges E1, E2 and E3, or
110         -- -   from four edges E1, E2, E3 and E4.
111         -- Further edges can be added using the function Add.
112         -- Given edges are added in a sequence. Each of them
113         -- must be connectable to the wire under construction,
114         -- and so must satisfy the following condition (unless it is
115         -- the first edge of the wire): one of its vertices must be
116         -- geometrically coincident with one of the vertices of the
117         -- wire (provided that the highest tolerance factor is
118         -- assigned to the two vertices). It could also be the same vertex.
119         -- Warning
120         -- If an edge is not connectable to the wire under
121         -- construction it is not added. The function Error will
122         -- return BRepBuilderAPI_DisconnectedWire, the
123         -- function IsDone will return false and the function Wire
124         -- will raise an error, until a new connectable edge is added.  
125         
126     ----------------------------------------------
127     -- From wire and edge
128     ----------------------------------------------
129
130     Create(W : Wire from TopoDS)                        
131         ---Purpose: Make a Wire from a Wire. Usefull for adding later.
132         ---Level: Public
133     returns MakeWire from BRepBuilderAPI;
134
135     Create(W : Wire from TopoDS; E : Edge from TopoDS)  
136         ---Purpose: Add an edge to a wire.
137         ---Level: Public
138     returns MakeWire from BRepBuilderAPI;
139         
140     ----------------------------------------------
141     -- Auxiliary methods
142     ----------------------------------------------
143
144     Add(me : in out; E : Edge from TopoDS)
145         ---Purpose:  Adds the edge E to the wire under construction.
146         -- E must be connectable to the wire under construction, and, unless it
147         -- is the first edge of the wire, must satisfy the following
148         -- condition: one of its vertices must be geometrically coincident
149         -- with one of the vertices of the wire (provided that the highest
150         -- tolerance factor is assigned to the two vertices). It could also
151         -- be the same vertex.
152         -- Warning
153         -- If E is not connectable to the wire under construction it is not
154         -- added. The function Error will return
155         -- BRepBuilderAPI_DisconnectedWire, the function IsDone will return
156         -- false and the function Wire will raise an error, until a new
157         -- connectable edge is added.
158     is static;
159     
160     Add(me : in out; W : Wire from TopoDS)
161         ---Purpose: Add the edges of <W> to the current wire.
162         ---Level: Public
163     is static;
164     
165     Add(me : in out; L : ListOfShape from TopTools)
166         ---Purpose: Adds  the edges of <L>   to the current  wire.  The
167         --          edges are not to be consecutive.   But they are to
168         --          be  all  connected geometrically or topologically.
169         --          If some of them are  not connected the Status give
170         --          DisconnectedWire but the "Maker" is Done() and you
171         --          can get the  partial result. (ie connected to  the
172         --          first edgeof the list <L>)
173         is static;
174     
175     ----------------------------------------------
176     -- Results
177     ----------------------------------------------
178
179     IsDone(me) returns Boolean
180         ---Purpose: Returns true if this algorithm contains a valid wire.
181         -- IsDone returns false if:
182         -- -   there are no edges in the wire, or
183         -- -   the last edge which you tried to add was not connectable.
184     is redefined;
185
186     Error(me) returns WireError from BRepBuilderAPI
187         ---Purpose: Returns the construction status
188         -- -   BRepBuilderAPI_WireDone if the wire is built, or
189         -- -   another value of the BRepBuilderAPI_WireError
190         --   enumeration indicating why the construction failed.
191     is static;
192
193     Wire(me) returns Wire from TopoDS
194         ---Purpose: Returns the constructed wire; or the part of the wire
195         -- under construction already built.
196         -- Exceptions StdFail_NotDone if a wire is not built.
197         ---C++: return const &
198         ---C++: alias "Standard_EXPORT operator TopoDS_Wire() const;"
199          raises
200         NotDone from StdFail
201     is static;
202     
203     Edge(me) returns Edge from TopoDS
204         ---C++: return const &
205         ---Purpose: Returns the last edge added to the wire under construction.
206         -- Warning
207         -- -   This edge can be different from the original one (the
208         --   argument of the function Add, for instance,)
209         -- -   A null edge is returned if there are no edges in the
210         --   wire under construction, or if the last edge which you
211         --   tried to add was not connectable..
212             raises
213         NotDone from StdFail
214     is static;
215     
216     Vertex(me) returns Vertex from TopoDS
217         ---C++: return const &
218         ---Purpose: Returns the last vertex of the last edge added to the
219         -- wire under construction.
220         -- Warning
221         -- A null vertex is returned if there are no edges in the wire
222         -- under construction, or if the last edge which you tried to
223         -- add was not connectableR
224     raises
225         NotDone from StdFail
226     is static;
227      
228
229 fields
230     myMakeWire : MakeWire from BRepLib;
231
232 end MakeWire;