[occt.git] / src / XSControl / XSControl_Reader.cdl

-- Created on: 1997-05-14
-- Created by: Christian CAILLET
-- Copyright (c) 1997-1999 Matra Datavision
-- Copyright (c) 1999-2014 OPEN CASCADE SAS
--
-- This file is part of Open CASCADE Technology software library.
--
-- This library is free software; you can redistribute it and / or modify it
-- under the terms of the GNU Lesser General Public version 2.1 as published
-- by the Free Software Foundation, with special exception defined in the file
-- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
-- distribution for complete text of the license and disclaimer of any warranty.
--
-- Alternatively, this file may be used under the terms of Open CASCADE
-- commercial license or contractual agreement.

class Reader  from XSControl

    	---Purpose : 
    	-- A groundwork to convert a shape to data which complies
    	-- with a particular norm. This data can be that of a whole
    	-- model or that of a specific list of entities in the model.
    	-- You specify the list using a single selection or a
    	-- combination of selections. A selection is an operator which
    	-- computes a list of entities from a list given in input. To
    	-- specify the input, you can use:
    	-- - A predefined selection such as "xst-transferrable-roots"
    	-- - A filter based on a  signature.
    	-- A signature is an operator which returns a string from an
    	-- entity according to its type.
    	-- For example:
    	-- - "xst-type" (CDL)
    	-- - "iges-level"
    	-- - "step-type".
    	-- A filter can be based on a signature by giving a value to
    	-- be matched by the string returned. For example,
    	-- "xst-type(Curve)".
    	-- If no list is specified, the selection computes its list of
    	-- entities from the whole model. To use this class, you have to
    	-- initialize the transfer norm first, as shown in the example below.
    	-- Example:
    	-- Control_Reader reader;
    	-- IFSelect_ReturnStatus status = reader.ReadFile (filename.);
    	-- When using IGESControl_Reader or STEPControl_Reader - as the
    	-- above example shows - the reader initializes the norm directly.
    	-- Note that loading the file only stores the data. It does
    	-- not translate this data. Shapes are accumulated by
    	-- successive transfers. The last shape is cleared by:
    	-- - ClearShapes which allows you to handle a new batch
    	-- - TransferRoots which restarts the list of shapes from scratch.

uses CString, OStream, Transient,
     SequenceOfTransient from TColStd, HSequenceOfTransient from TColStd,
     InterfaceModel from Interface, WorkSession from XSControl,
     ReturnStatus from IFSelect, PrintCount from IFSelect,
     Shape from TopoDS, SequenceOfShape from TopTools

is

    Create returns Reader;
    ---Purpose : Creates a Reader from scratch (creates an empty WorkSession)
    --           A WorkSession or a Controller must be provided before running

    Create (norm : CString) returns Reader;
    ---Purpose : Creates a Reader from scratch, with a norm name which
    --           identifies a Controller

    Create (WS : mutable WorkSession from XSControl;
    	    	 scratch : Boolean = Standard_True) returns Reader;
    ---Purpose : Creates a Reader from an already existing Session, with a
    --           Controller already set

    ---Purpose: Virtual destructor 
    ---C++ : alias "Standard_EXPORT virtual ~XSControl_Reader() {}"

    SetNorm (me : in out; norm : CString) returns Boolean;
    ---Purpose : Sets a specific norm to <me>
    --           Returns True if done, False if <norm> is not available

    SetWS (me : in out; WS : mutable WorkSession from XSControl;
    	    	 scratch : Boolean = Standard_True);
    ---Purpose : Sets a specific session to <me>

    WS (me) returns WorkSession from XSControl;
    ---Purpose : Returns the session used in <me>


    ReadFile (me : in out; filename : CString) returns ReturnStatus;
    ---Purpose : Loads a file and returns the read status
    --           Zero for a Model which compies with the Controller

    Model (me) returns InterfaceModel;
    ---Purpose : Returns the model. It can then be consulted (header, product)

    GiveList (me : in out; first, second : CString = "")
    	returns HSequenceOfTransient from TColStd;
    	---Purpose : Returns a list of entities from the IGES or STEP file 
    	-- according to the following rules:
    	-- - if first and second are empty strings, the whole file is selected.
    	-- - if first is an entity number or label, the entity referred to is selected.
    	-- - if first is a list of entity numbers/labels separated by commas, the entities referred to are selected,
    	-- - if first is the name of a selection in the worksession and second is not defined,
    	-- the list contains the standard output for that selection.
    	-- - if first is the name of a selection and second is defined, the criterion defined
    	-- by second is applied to the result of the first selection.
    	--  A selection is an operator which computes a list of entities from a list given in
    	-- input according to its type. If no list is specified, the selection computes its
    	-- list of entities from the whole model.
    	--   A selection can be:
    	-- - A predefined selection (xst-transferrable-mode)
    	-- - A filter based on a signature
    	-- A Signature is an operator which returns a string from an entity according to its type. For example:
    	-- - "xst-type" (CDL)
    	-- - "iges-level"
    	-- - "step-type".
    	-- For example, if you wanted to select only the advanced_faces in a STEP file you
    	-- would use the following code:
    	-- Example
    	-- Reader.GiveList("xst-transferrable-roots","step-type(ADVANCED_FACE)");
    	-- Warning
    	-- If the value given to second is incorrect, it will simply be ignored.

    GiveList (me : in out; first : CString; ent : Transient)
    	returns HSequenceOfTransient from TColStd;
    ---Purpose : Computes a List of entities from the model as follows
    --           <first> beeing a Selection, <ent> beeing an entity or a list
    --           of entities (as a HSequenceOfTransient) :
    --             the standard result of this selection applied to this list
    --           if <first> is erroneous, a null handle is returned


    NbRootsForTransfer (me : in out) returns Integer is virtual ;
    ---Purpose : Determines the list of root entities which are candidate for
    --           a transfer to a Shape, and returns the number
    --           of entities in the list

    RootForTransfer (me : in out; num : Integer = 1) returns Transient;
    ---Purpose : Returns an IGES or STEP root
    --           entity for translation. The entity is identified by its
    --           rank in a list.

    TransferOneRoot (me : in out; num : Integer = 1) returns Boolean ;
    ---Purpose : Translates a root identified by the rank num in the model.
    --           false is returned if no shape is produced.
    
    TransferOne  (me : in out; num : Integer) returns Boolean;
    ---Purpose : Translates an IGES or STEP
    --           entity identified by the rank num in the model.
    --           false is returned if no shape is produced.

    TransferEntity (me : in out; start : Transient) returns Boolean;
    ---Purpose : Translates an IGES or STEP
    --           entity in the model. true is returned if a shape is
    --           produced; otherwise, false is returned.

    TransferList (me : in out; list : HSequenceOfTransient from TColStd)
    	returns Integer;
    ---Purpose : Translates a list of entities.
    --           Returns the number of IGES or STEP entities that were
    --           successfully translated. The list can be produced with GiveList.
    --           Warning - This function does not clear the existing output shapes.

    TransferRoots (me : in out) returns Integer;
    ---Purpose : Translates all translatable
    --           roots and returns the number of successful translations.
    --           Warning - This function clears existing output shapes first.


    ClearShapes (me : in out);
    ---Purpose : Clears the list of shapes that
    --           may have accumulated in calls to TransferOne or TransferRoot.C

    NbShapes (me) returns Integer;
    ---Purpose : Returns the number of shapes produced by translation.

    Shapes (me: in out) returns SequenceOfShape from TopTools is protected;
    ---Purpose : Returns a sequence of produced shapes
    ---C++: return &
    
    Shape (me; num : Integer = 1) returns Shape from TopoDS;
    	---Purpose : Returns the shape resulting
    	-- from a translation and identified by the rank num.
    	-- num equals 1 by default. In other words, the first shape
    	-- resulting from the translation is returned.

    OneShape (me) returns Shape from TopoDS;
    	---Purpose : Returns all of the results in
    	-- a single shape which is:
    	-- - a null shape if there are no results,
    	-- - a shape if there is one result,
    	-- - a compound containing the resulting shapes if there are more than one.

    PrintCheckLoad (me; failsonly : Boolean; mode : PrintCount);
    ---Purpose : Prints the check list attached to loaded data, on the Standard
    --            Trace File (starts at cout)
    --           All messages or fails only, according to <failsonly>
    --           mode = 0 : per entity, prints messages
    --           mode = 1 : per message, just gives count of entities per check
    --           mode = 2 : also gives entity numbers

    PrintCheckTransfer (me; failsonly : Boolean; mode : PrintCount);
    	---Purpose : Displays check results for the
    	-- last translation of IGES or STEP entities to Open CASCADE
    	-- entities. Only fail messages are displayed if failsonly is
    	-- true. All messages are displayed if failsonly is
    	-- false. mode determines the contents and the order of the
    	-- messages according to the terms of the IFSelect_PrintCount enumeration.

    PrintStatsTransfer (me; what : Integer; mode : Integer = 0);
    	---Purpose :  Displays the statistics for
    	-- the last translation. what defines the kind of
    	-- statistics that are displayed as follows:
    	-- - 0 gives general statistics (number of translated roots,
    	-- number of warnings, number of fail messages),
    	-- - 1 gives root results,
    	--    - 2 gives statistics for all checked entities,
    	-- - 3 gives the list of translated entities,
    	-- - 4 gives warning and fail messages,
    	-- - 5 gives fail messages only.
    	-- The use of mode depends on the value of what. If what is 0,
    	-- mode is ignored. If what is 1, 2 or 3, mode defines the following:
    	-- - 0 lists the numbers of IGES or STEP entities in the respective model
    	-- - 1 gives the number, identifier, type and result
    	-- type for each IGES or STEP entity and/or its status
    	-- (fail, warning, etc.)
    	-- - 2 gives maximum information for each IGES or STEP entity (i.e. checks)
    	-- - 3 gives the number of entities per type of IGES or STEP entity
    	-- - 4 gives the number of IGES or STEP entities per result type and/or status
    	-- - 5 gives the number of pairs (IGES or STEP or result type and status)
    	-- - 6 gives the number of pairs (IGES or STEP or result type
    	-- and status) AND the list of entity numbers in the IGES or STEP model.
    	--   If what is 4 or 5, mode defines the warning and fail
    	-- messages as follows:
    	-- - if mode is 0 all warnings and checks per entity are returned
    	-- - if mode is 2 the list of entities per warning is returned.
    	--   If mode is not set, only the list of all entities per warning is given.
    
    GetStatsTransfer (me; list: HSequenceOfTransient from TColStd;
    	    	    	  nbMapped    : out Integer;
			  nbWithResult: out Integer;
			  nbWithFail  : out Integer);
    	---Purpose: Gives statistics about Transfer

fields

    thesession : WorkSession from XSControl;
    therootsta : Boolean is protected;              -- are roots determined
    theroots   : SequenceOfTransient is protected;  -- only roots available for Transfer
    theshapes  : SequenceOfShape;

end Reader;
Commit	Line	Data
b311480e	1	-- Created on: 1997-05-14
	2	-- Created by: Christian CAILLET
	3	-- Copyright (c) 1997-1999 Matra Datavision
973c2be1	4	-- Copyright (c) 1999-2014 OPEN CASCADE SAS
b311480e	5	--
973c2be1	6	-- This file is part of Open CASCADE Technology software library.
b311480e	7	--
973c2be1	8	-- This library is free software; you can redistribute it and / or modify it
	9	-- under the terms of the GNU Lesser General Public 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.
b311480e	13	--
973c2be1	14	-- Alternatively, this file may be used under the terms of Open CASCADE
973c2be1	15	-- commercial license or contractual agreement.
7fd59977	16
	17	class Reader from XSControl
	18
	19	---Purpose :
	20	-- A groundwork to convert a shape to data which complies
	21	-- with a particular norm. This data can be that of a whole
	22	-- model or that of a specific list of entities in the model.
	23	-- You specify the list using a single selection or a
	24	-- combination of selections. A selection is an operator which
	25	-- computes a list of entities from a list given in input. To
	26	-- specify the input, you can use:
	27	-- - A predefined selection such as "xst-transferrable-roots"
	28	-- - A filter based on a signature.
	29	-- A signature is an operator which returns a string from an
	30	-- entity according to its type.
	31	-- For example:
	32	-- - "xst-type" (CDL)
	33	-- - "iges-level"
	34	-- - "step-type".
	35	-- A filter can be based on a signature by giving a value to
	36	-- be matched by the string returned. For example,
	37	-- "xst-type(Curve)".
	38	-- If no list is specified, the selection computes its list of
	39	-- entities from the whole model. To use this class, you have to
	40	-- initialize the transfer norm first, as shown in the example below.
	41	-- Example:
	42	-- Control_Reader reader;
	43	-- IFSelect_ReturnStatus status = reader.ReadFile (filename.);
	44	-- When using IGESControl_Reader or STEPControl_Reader - as the
	45	-- above example shows - the reader initializes the norm directly.
	46	-- Note that loading the file only stores the data. It does
	47	-- not translate this data. Shapes are accumulated by
	48	-- successive transfers. The last shape is cleared by:
	49	-- - ClearShapes which allows you to handle a new batch
	50	-- - TransferRoots which restarts the list of shapes from scratch.
	51
	52	uses CString, OStream, Transient,
	53	SequenceOfTransient from TColStd, HSequenceOfTransient from TColStd,
	54	InterfaceModel from Interface, WorkSession from XSControl,
	55	ReturnStatus from IFSelect, PrintCount from IFSelect,
	56	Shape from TopoDS, SequenceOfShape from TopTools
	57
	58	is
	59
	60	Create returns Reader;
	61	---Purpose : Creates a Reader from scratch (creates an empty WorkSession)
	62	-- A WorkSession or a Controller must be provided before running
	63
	64	Create (norm : CString) returns Reader;
	65	---Purpose : Creates a Reader from scratch, with a norm name which
	66	-- identifies a Controller
	67
	68	Create (WS : mutable WorkSession from XSControl;
	69	scratch : Boolean = Standard_True) returns Reader;
	70	---Purpose : Creates a Reader from an already existing Session, with a
	71	-- Controller already set
	72
	73	---Purpose: Virtual destructor
	74	---C++ : alias "Standard_EXPORT virtual ~XSControl_Reader() {}"
	75
	76	SetNorm (me : in out; norm : CString) returns Boolean;
	77	---Purpose : Sets a specific norm to <me>
	78	-- Returns True if done, False if <norm> is not available
	79
80	SetWS (me : in out; WS : mutable WorkSession from XSControl;
81	scratch : Boolean = Standard_True);
82	---Purpose : Sets a specific session to <me>
83
84	WS (me) returns WorkSession from XSControl;
85	---Purpose : Returns the session used in <me>
86
87
88	ReadFile (me : in out; filename : CString) returns ReturnStatus;
89	---Purpose : Loads a file and returns the read status
90	-- Zero for a Model which compies with the Controller
91
92	Model (me) returns InterfaceModel;
93	---Purpose : Returns the model. It can then be consulted (header, product)
94
95	GiveList (me : in out; first, second : CString = "")
96	returns HSequenceOfTransient from TColStd;
97	---Purpose : Returns a list of entities from the IGES or STEP file
98	-- according to the following rules:
99	-- - if first and second are empty strings, the whole file is selected.
100	-- - if first is an entity number or label, the entity referred to is selected.
101	-- - if first is a list of entity numbers/labels separated by commas, the entities referred to are selected,
102	-- - if first is the name of a selection in the worksession and second is not defined,
103	-- the list contains the standard output for that selection.
104	-- - if first is the name of a selection and second is defined, the criterion defined
105	-- by second is applied to the result of the first selection.
106	-- A selection is an operator which computes a list of entities from a list given in
107	-- input according to its type. If no list is specified, the selection computes its
108	-- list of entities from the whole model.
109	-- A selection can be:
110	-- - A predefined selection (xst-transferrable-mode)
111	-- - A filter based on a signature
112	-- A Signature is an operator which returns a string from an entity according to its type. For example:
113	-- - "xst-type" (CDL)
114	-- - "iges-level"
115	-- - "step-type".
116	-- For example, if you wanted to select only the advanced_faces in a STEP file you
117	-- would use the following code:
118	-- Example
119	-- Reader.GiveList("xst-transferrable-roots","step-type(ADVANCED_FACE)");
120	-- Warning
121	-- If the value given to second is incorrect, it will simply be ignored.
122
123	GiveList (me : in out; first : CString; ent : Transient)
124	returns HSequenceOfTransient from TColStd;
125	---Purpose : Computes a List of entities from the model as follows
126	-- <first> beeing a Selection, <ent> beeing an entity or a list
127	-- of entities (as a HSequenceOfTransient) :
128	-- the standard result of this selection applied to this list
129	-- if <first> is erroneous, a null handle is returned
130
131
132	NbRootsForTransfer (me : in out) returns Integer is virtual ;
133	---Purpose : Determines the list of root entities which are candidate for
134	-- a transfer to a Shape, and returns the number
135	-- of entities in the list
136
137	RootForTransfer (me : in out; num : Integer = 1) returns Transient;
138	---Purpose : Returns an IGES or STEP root
139	-- entity for translation. The entity is identified by its
140	-- rank in a list.
141
142	TransferOneRoot (me : in out; num : Integer = 1) returns Boolean ;
143	---Purpose : Translates a root identified by the rank num in the model.
144	-- false is returned if no shape is produced.
145
146	TransferOne (me : in out; num : Integer) returns Boolean;
147	---Purpose : Translates an IGES or STEP
148	-- entity identified by the rank num in the model.
149	-- false is returned if no shape is produced.
150
151	TransferEntity (me : in out; start : Transient) returns Boolean;
152	---Purpose : Translates an IGES or STEP
153	-- entity in the model. true is returned if a shape is
154	-- produced; otherwise, false is returned.
155
156	TransferList (me : in out; list : HSequenceOfTransient from TColStd)
157	returns Integer;
158	---Purpose : Translates a list of entities.
159	-- Returns the number of IGES or STEP entities that were
160	-- successfully translated. The list can be produced with GiveList.
161	-- Warning - This function does not clear the existing output shapes.
162
163	TransferRoots (me : in out) returns Integer;
164	---Purpose : Translates all translatable
165	-- roots and returns the number of successful translations.
166	-- Warning - This function clears existing output shapes first.
167
168
169	ClearShapes (me : in out);
170	---Purpose : Clears the list of shapes that
171	-- may have accumulated in calls to TransferOne or TransferRoot.C
172
173	NbShapes (me) returns Integer;
174	---Purpose : Returns the number of shapes produced by translation.
175
176	Shapes (me: in out) returns SequenceOfShape from TopTools is protected;
177	---Purpose : Returns a sequence of produced shapes
178	---C++: return &
179
180	Shape (me; num : Integer = 1) returns Shape from TopoDS;
181	---Purpose : Returns the shape resulting
182	-- from a translation and identified by the rank num.
183	-- num equals 1 by default. In other words, the first shape
184	-- resulting from the translation is returned.
185
186	OneShape (me) returns Shape from TopoDS;
187	---Purpose : Returns all of the results in
188	-- a single shape which is:
189	-- - a null shape if there are no results,
190	-- - a shape if there is one result,
191	-- - a compound containing the resulting shapes if there are more than one.
192
193	PrintCheckLoad (me; failsonly : Boolean; mode : PrintCount);
194	---Purpose : Prints the check list attached to loaded data, on the Standard
195	-- Trace File (starts at cout)
196	-- All messages or fails only, according to <failsonly>
197	-- mode = 0 : per entity, prints messages
198	-- mode = 1 : per message, just gives count of entities per check
199	-- mode = 2 : also gives entity numbers
200
201	PrintCheckTransfer (me; failsonly : Boolean; mode : PrintCount);
202	---Purpose : Displays check results for the
203	-- last translation of IGES or STEP entities to Open CASCADE
204	-- entities. Only fail messages are displayed if failsonly is
205	-- true. All messages are displayed if failsonly is
206	-- false. mode determines the contents and the order of the
207	-- messages according to the terms of the IFSelect_PrintCount enumeration.
208
209	PrintStatsTransfer (me; what : Integer; mode : Integer = 0);
210	---Purpose : Displays the statistics for
211	-- the last translation. what defines the kind of
212	-- statistics that are displayed as follows:
213	-- - 0 gives general statistics (number of translated roots,
214	-- number of warnings, number of fail messages),
215	-- - 1 gives root results,
216	-- - 2 gives statistics for all checked entities,
217	-- - 3 gives the list of translated entities,
218	-- - 4 gives warning and fail messages,
219	-- - 5 gives fail messages only.
220	-- The use of mode depends on the value of what. If what is 0,
221	-- mode is ignored. If what is 1, 2 or 3, mode defines the following:
222	-- - 0 lists the numbers of IGES or STEP entities in the respective model
223	-- - 1 gives the number, identifier, type and result
224	-- type for each IGES or STEP entity and/or its status
225	-- (fail, warning, etc.)
226	-- - 2 gives maximum information for each IGES or STEP entity (i.e. checks)
227	-- - 3 gives the number of entities per type of IGES or STEP entity
228	-- - 4 gives the number of IGES or STEP entities per result type and/or status
229	-- - 5 gives the number of pairs (IGES or STEP or result type and status)
230	-- - 6 gives the number of pairs (IGES or STEP or result type
231	-- and status) AND the list of entity numbers in the IGES or STEP model.
232	-- If what is 4 or 5, mode defines the warning and fail
233	-- messages as follows:
234	-- - if mode is 0 all warnings and checks per entity are returned
235	-- - if mode is 2 the list of entities per warning is returned.
236	-- If mode is not set, only the list of all entities per warning is given.
237
238	GetStatsTransfer (me; list: HSequenceOfTransient from TColStd;
239	nbMapped : out Integer;
240	nbWithResult: out Integer;
241	nbWithFail : out Integer);
242	---Purpose: Gives statistics about Transfer
243
244	fields
245
246	thesession : WorkSession from XSControl;
247	therootsta : Boolean is protected; -- are roots determined
248	theroots : SequenceOfTransient is protected; -- only roots available for Transfer
249	theshapes : SequenceOfShape;
250
251	end Reader;