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