Test for 0022778: Bug in BRepMesh
[occt.git] / src / XSControl / XSControl_Utils.cdl
1 -- Created on: 1995-12-04
2 -- Created by: Christian CAILLET
3 -- Copyright (c) 1995-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 class Utils  from XSControl
24
25     ---Purpose : This class provides various useful utility routines, to
26     --           facilitate handling of most common data structures :
27     --           transients (type, type name ...),
28     --           strings (ascii or extended, pointed or handled or ...),
29     --           shapes (reading, writing, testing ...),
30     --           sequences & arrays (of strings, of transients, of shapes ...),
31     --           ...
32     --           
33     --           Also it gives some helps on some data structures from XSTEP,
34     --           such as printing on standard trace file, recignizing most
35     --           currently used auxiliary types (Binder,Mapper ...)
36
37 uses CString, ExtString, Transient,
38      AsciiString, HAsciiString,  ExtendedString, HExtendedString,
39      HSequenceOfInteger from TColStd,
40      HSequenceOfTransient, HSequenceOfHAsciiString, HSequenceOfHExtendedString,
41      Shape from TopoDS, HSequenceOfShape from TopTools, ShapeEnum from TopAbs,
42      Binder from Transfer
43
44 raises TypeMismatch
45
46 is
47
48     Create returns Utils;
49     ---Purpose : the only use of this, is to allow a frontal to get one
50     --           distinct "Utils" set per separate engine
51
52         --    Trace File
53         -- the class TraceFile gives enough functions to work from ccl
54         -- except to print a line to the default trace file (ccl can't call it)
55
56     TraceLine  (me; line : CString);
57     ---Purpose : Just prints a line into the current Trace File. This allows to
58     --           better characterise the various trace outputs, as desired.
59
60     TraceLines (me; lines : Transient);
61     ---Purpose : Just prints a line or a set of lines into the current Trace
62     --           File. <lines> can be a HAscii/ExtendedString (produces a print
63     --           without ending line) or a HSequence or HArray1 Of ..
64     --            (one new line per item)
65
66         -- General Functions on Sequences : below
67
68         --    Simple Transient Objects (complements)    --
69
70     IsKind   (me; item : Transient; what : Type) returns Boolean;
71     -- simply IsKind from Transient
72
73     TypeName (me; item : Transient; nopk : Boolean = Standard_False)
74          returns CString;
75     ---Purpose : Returns the name of the dynamic type of an object, i.e. :
76     --           If it is a Type, its Name
77     --           If it is a object not a type, the Name of its DynamicType
78     --           If it is Null, an empty string
79     --           If <nopk> is False (D), gives complete name
80     --           If <nopk> is True, returns class name without package
81
82         --    List of Transients (HSequence or HArray1)    --
83
84     TraValue  (me; list : Transient; num : Integer)
85         returns mutable Transient;
86     --  allowed : HSequenceOfTransient    -> Transient,
87     --            HSequenceOfHAsciiString -> HAsciiString
88     --  out of range gives Null Handle
89     NewSeqTra (me) returns mutable HSequenceOfTransient;    -- empty new
90     AppendTra (me; seqval : mutable HSequenceOfTransient;
91                         traval : Transient);
92
93         --    Dates
94
95     DateString (me; yy,mm,dd,hh,mn,ss : Integer) returns CString;
96     DateValues (me; text : CString; yy,mm,dd,hh,mn,ss : out Integer);
97
98         --    --    Strings    --    --
99         --    Ascii    --
100
101     ToCString (me; strval : HAsciiString) returns CString;
102     ToCString (me; strval :  AsciiString) returns CString;
103     ToHString (me; strcon : CString) returns mutable HAsciiString;
104     ToAString (me; strcon : CString) returns AsciiString;
105
106         --    Extended    --
107
108     ToEString (me; strval : HExtendedString) returns ExtString;
109     ToEString (me; strval :  ExtendedString) returns ExtString;
110     ToHString (me; strcon : ExtString) returns mutable HExtendedString;
111     ToXString (me; strcon : ExtString) returns ExtendedString;
112
113         --    Ascii <-> Extended    --
114
115     AsciiToExtended (me; str : CString)   returns ExtString;
116     IsAscii         (me; str : ExtString) returns Boolean;
117     ExtendedToAscii (me; str : ExtString) returns CString;
118
119         --    List of Strings    --
120
121     CStrValue  (me; list : Transient; num : Integer) returns CString;
122     EStrValue  (me; list : Transient; num : Integer) returns ExtString;
123     --  list : HSequence or HArray1 of (H)AsciiString or (H)ExtendedString
124     --  conversions Ascii<->Extended are done if required
125     --  out of range gives empty string
126
127     NewSeqCStr (me) returns mutable HSequenceOfHAsciiString;      -- empty
128     AppendCStr (me; seqval : mutable HSequenceOfHAsciiString;
129                          strval : CString);
130     NewSeqEStr (me) returns mutable HSequenceOfHExtendedString;   -- empty
131     AppendEStr (me; seqval : mutable HSequenceOfHExtendedString;
132                          strval : ExtString);
133
134         --    --    Shapes    --    --
135         --    Direct Handling, Read-Write    --
136
137     WriteShape (me; shape : Shape from TopoDS; filename : CString)
138         returns Boolean;
139     ---Purpose : Writes a Shape under the internal BRepTools form
140     --           (an internal help utility)
141     --           Returns True if writing has succeeded, False else
142
143     NewShape   (me) returns Shape from TopoDS;
144     ---Purpose : Returns a new empty, undefined Shape, which can then be filled
145     --           by ReadShape
146
147     ReadShape  (me; shape : in out Shape from TopoDS; filename : CString)
148         returns Boolean;
149     ---Purpose : Reads a Shape from the internal BRepTools form and returns it
150     --           (an internal help utility)
151     --           Returns True if reading has succeeded, False else
152
153     IsNullShape (me; shape : Shape from TopoDS) returns Boolean;
154     ---Purpose : Returns True if a Shape is Null
155
156     CompoundFromSeq (me; seqval : HSequenceOfShape)
157         returns Shape from TopoDS;
158     ---Purpose : Converts a list of Shapes to a Compound (a kind of Shape)
159
160     ShapeType  (me; shape : Shape from TopoDS; compound : Boolean)
161         returns ShapeEnum;
162     ---Purpose : Returns the type of a Shape : true type if <compound> is False
163     --           If <compound> is True and <shape> is a Compound, iterates on
164     --           its items. If all are of the same type, returns this type.
165     --           Else, returns COMPOUND. If it is empty, returns SHAPE
166     --           For a Null Shape, returns SHAPE
167
168     SortedCompound (me; shape : Shape from TopoDS; type : ShapeEnum;
169                     explore : Boolean; compound : Boolean)
170         returns Shape from TopoDS;
171     ---Purpose : From a Shape, builds a Compound as follows :
172     --           explores it level by level
173     --           If <explore> is False, only COMPOUND items. Else, all items
174     --           Adds to the result, shapes which comply to <type>
175     --           + if <type> is WIRE, considers free edges (and makes wires)
176     --           + if <type> is SHELL, considers free faces (and makes shells)
177     --           If <compound> is True, gathers items in compounds which
178     --           correspond to starting COMPOUND,SOLID or SHELL containers, or
179     --           items directly contained in a Compound
180
181         --    --    List of Shapes    --    --
182
183     ShapeValue  (me; seqv : HSequenceOfShape from TopTools; num : Integer)
184         returns Shape from TopoDS;
185     --  out of range gives Null Handle
186     NewSeqShape (me) returns mutable HSequenceOfShape;    -- empty new
187     AppendShape (me; seqv  : mutable HSequenceOfShape;
188                           shape : Shape from TopoDS);
189
190         --    Shape <-> Transient    --
191
192     ShapeBinder (me; shape : Shape from TopoDS; hs : Boolean = Standard_True)
193         returns mutable Transient;
194     ---Purpose : Creates a Transient Object from a Shape : it is either a Binder
195     --           (used by functions which require a Transient but can process
196     --           a Shape, such as viewing functions) or a HShape (according to hs)
197     --           Default is a HShape
198
199     BinderShape (me; tr : Transient) returns Shape from TopoDS;
200     ---Purpose : From a Transient, returns a Shape.
201     --           In fact, recognizes ShapeBinder ShapeMapper and HShape
202
203         --    --    Lists : others functions    --    --
204
205     SeqLength (me; list : Transient) returns Integer;
206     --  list : HSequence of Transient,(H)Ascii/ExtendedString,Shape,Integer
207
208     SeqToArr  (me; seq : Transient; first : Integer = 1)
209         returns mutable Transient   raises TypeMismatch;
210     --   <first> gives the lower index of produced array
211     --   empty sequence gives a null handle
212     ArrToSeq  (me; arr : Transient)
213         returns mutable Transient   raises TypeMismatch;
214     -- allowed combinations :
215     --    HSequenceOfTransient       <-> HArray1OfTransient
216     --    HSequenceOfHAsciiString    <-> HArray1OfHAsciiString (from Interface)
217     --    Arrays are build from index <first>, by default 1
218
219     SeqIntValue (me; list : HSequenceOfInteger from TColStd; num : Integer)
220         returns Integer;
221
222 end Utils;