[occt.git] / src / Interface / Interface_STAT.cdl

-- File:	Interface_STAT.cdl
-- Created:	Thu Feb 15 16:45:14 1996
-- Author:	Christian CAILLET
--		<cky@fidox>
---Copyright:	 Matra Datavision 1996


class STAT  from Interface

    ---Purpose : This class manages statistics to be queried asynchronously.
    --           Way of use :
    --           An operator describes a STAT form then fills it according to
    --           its progression. This produces a state of advancement of the
    --           process. This state can then be queried asynchronously :
    --           typically it is summarised as a percentage. There are also
    --           an identification of the current state, and informations on
    --           processed volume.
    --           
    --           A STAT form can be described once for all (as static).
    --           It describes the stream of the process (see later), in terms
    --           of phases, cycles, steps, with estimated weights. But it
    --           brings no current data.
    --           
    --           One STAT at a time is active for filling and querying. It is
    --           used to control phasing, weighting ... Specific data for
    --           execution are given when running on active STAT : counts of
    --           items ... Data for query are then recorded and can be accessed
    --           at any time, asynchronously.
    --           
    --           A STAT is organised as follows :
    --           - it can be split into PHASES (by default, there is none, and
    --             all process takes place in one "default" phase)
    --           - each phase is identified by a name and is attached a weight
    --           -> the sum of the weights is used to compute relative weights
    --           - for each phase, or for the unique default phase if none :
    --           -- the process works on a list of ITEMS
    --           -- by default, all the items are processed in once
    --           -- but this list can be split into CYCLES, each one takes
    --              a sub-list : the weight of each cycle is related to its
    --              count of items
    --           -- a cycle can be split into STEPS, by default there are none
    --              then one "default step" is considered
    --           -- each step is attached a weight
    --           -> the sum of the weights of steps is used to compute relative
    --              weights of the steps in each cycle
    --           -> all the cycles of a phase have the same organisation
    --           
    --           Hence, when defining the STAT form, the phases have to be
    --           described. If no weight is precisely known, give 1. for all...
    --           No phase description will give only one "default" phase
    --           For each phase, a typical cycle can be described by its steps.
    --           Here too, for no weight precisely known, give 1. for all...
    --           
    --           For executing, activate a STAT to begin count. Give counts of
    --           items and cycles for the first phase (for the unique default
    --           one if no phasing is described)
    --           Else, give count of items and cycles for each new phase.
    --           Class methods allow also to set next cycle (given count of
    --           items), next step in cycle (if more then one), next item in
    --           step.

uses Integer, Real, HSequenceOfInteger, HSequenceOfReal,
     CString, HAsciiString, HSequenceOfAsciiString

is

    	-- --    Description of a STAT form    -- --

    Create (title : CString = "") returns STAT;
    ---Purpose : Creates a STAT form. At start, one default phase is defined,
    --           with one default step. Then, it suffises to start with a
    --           count of items (and cycles if several) then record items,
    --           to have a queryable report.

    Create (other : STAT) returns STAT;
    ---Purpose : used when starting

    Internals (me; tit : out HAsciiString; total : out Real;
    	    	   phn : out HSequenceOfAsciiString; phw : out HSequenceOfReal;
		   phdeb, phfin : out HSequenceOfInteger;
    	    	   stw   : out HSequenceOfReal);
    ---Purpose : Returns fields in once, without copying them, used for copy
    --           when starting

    AddPhase (me : in out; weight : Real; name : CString = "");
    ---Purpose : Adds a new phase to the description.
    --           The first one after Create replaces the default unique one

    AddStep  (me : in out; weight : Real = 1);
    ---Purpose : Adds a new step for the last added phase, the default unique
    --           one if no AddPhase has already been added
    --  Warning : AddStep before the first AddPhase are cancelled

    Description (me; nbphases : out Integer; total : out Real; title : out CString);
    ---Purpose : Returns global description (cumulated weights of all phases,
    --           count of phases,1 for default, and title)

    Phase    (me;  num : Integer;n0step, nbstep : out Integer; weight : out Real; name : out CString);
    ---Purpose : Returns description of a phase, given its rank
    --           (n0 for first step, count of steps, default gives one;
    --            weight, name)

    Step     (me; num : Integer) returns Real;
    ---Purpose : Returns weight of a Step, related to the cumul given for the
    --           phase.
    --           <num> is given by <n0step> + i, i between 1 and <nbsteps>
    --           (default gives n0step < 0 then weight is one)

    	-- --   Running : Filling   -- --

    Start (me; items : Integer; cycles : Integer = 1);
    ---Purpose : Starts a STAT on its first phase (or its default one)
    --           <items> gives the total count of items, <cycles> the count of
    --           cycles
    --           If <cycles> is more than one, the first Cycle must then be
    --           started by NextCycle (NextStep/NextItem are ignored).
    --           If it is one, NextItem/NextStep can then be called

    StartCount (myclass; items : Integer; title : CString = "");
    ---Purpose : Starts a default STAT, with no phase, no step, ready to just
    --           count items.
    --           <items> gives the total count of items
    --           Hence, NextItem is available to directly count

    NextPhase (myclass; items : Integer; cycles : Integer = 1);
    ---Purpose : Commands to resume the preceeding phase and start a new one
    --           <items> and <cycles> as for Start, but for this new phase
    --           Ignored if count of phases is already passed
    --           If <cycles> is more than one, the first Cycle must then be
    --           started by NextCycle (NextStep/NextItem are ignored).
    --           If it is one, NextItem/NextStep can then be called

    SetPhase  (myclass; items : Integer; cycles : Integer = 1);
    ---Purpose : Changes the parameters of the phase to start
    --           To be used before first counting (i.e. just after NextPhase)
    --           Can be used by an operator which has to reajust counts on run

    NextCycle (myclass; items : Integer);
    ---Purpose : Commands to resume the preceeding cycle and start a new one,
    --           with a count of items
    --           Ignored if count of cycles is already passed
    --           Then, first step is started (or default one)
    --           NextItem can be called for the first step, or NextStep to pass
    --           to the next one

    NextStep  (myclass);
    ---Purpose : Commands to resume the preceeding step of the cycle
    --           Ignored if count of steps is already passed
    --           NextItem can be called for this step, NextStep passes to next

    NextItem  (myclass; nbitems : Integer = 1);
    ---Purpose : Commands to add an item in the current step of the current
    --           cycle of the current phase
    --           By default, one item per call, can be overpassed
    --           Ignored if count of items of this cycle is already passed

    End       (myclass);
    ---Purpose : Commands to declare the process ended (hence, advancement is
    --           forced to 100 %)

    	-- --   Running : Querying   -- --

    Where (myclass; phase : Boolean = Standard_True) returns CString;
    ---Purpose : Returns an identification of the STAT :
    --           <phase> True (D) : the name of the current phase
    --           <phase> False : the title of the current STAT

    Percent (myclass; phase : Boolean = Standard_False) returns Integer;
    ---Purpose : Returns the advancement as a percentage :
    --           <phase> True : inside the current phase
    --           <phase> False (D) : relative to the whole process

fields  -- used for description, not for running

    thetitle : HAsciiString;
    thetotal : Real;
    thephnam : HSequenceOfAsciiString;
    thephw   : HSequenceOfReal;
    thephdeb : HSequenceOfInteger;  -- nums of steps of each phase
    thephfin : HSequenceOfInteger;

    thestw   : HSequenceOfReal;

end STAT;
Commit	Line	Data
7fd59977	1	-- File: Interface_STAT.cdl
	2	-- Created: Thu Feb 15 16:45:14 1996
	3	-- Author: Christian CAILLET
	4	-- <cky@fidox>
	5	---Copyright: Matra Datavision 1996
	6
	7
	8	class STAT from Interface
	9
	10	---Purpose : This class manages statistics to be queried asynchronously.
	11	-- Way of use :
	12	-- An operator describes a STAT form then fills it according to
	13	-- its progression. This produces a state of advancement of the
	14	-- process. This state can then be queried asynchronously :
	15	-- typically it is summarised as a percentage. There are also
	16	-- an identification of the current state, and informations on
	17	-- processed volume.
	18	--
	19	-- A STAT form can be described once for all (as static).
	20	-- It describes the stream of the process (see later), in terms
	21	-- of phases, cycles, steps, with estimated weights. But it
	22	-- brings no current data.
	23	--
	24	-- One STAT at a time is active for filling and querying. It is
	25	-- used to control phasing, weighting ... Specific data for
	26	-- execution are given when running on active STAT : counts of
	27	-- items ... Data for query are then recorded and can be accessed
	28	-- at any time, asynchronously.
	29	--
	30	-- A STAT is organised as follows :
	31	-- - it can be split into PHASES (by default, there is none, and
	32	-- all process takes place in one "default" phase)
	33	-- - each phase is identified by a name and is attached a weight
	34	-- -> the sum of the weights is used to compute relative weights
	35	-- - for each phase, or for the unique default phase if none :
	36	-- -- the process works on a list of ITEMS
	37	-- -- by default, all the items are processed in once
	38	-- -- but this list can be split into CYCLES, each one takes
	39	-- a sub-list : the weight of each cycle is related to its
	40	-- count of items
	41	-- -- a cycle can be split into STEPS, by default there are none
	42	-- then one "default step" is considered
	43	-- -- each step is attached a weight
	44	-- -> the sum of the weights of steps is used to compute relative
	45	-- weights of the steps in each cycle
	46	-- -> all the cycles of a phase have the same organisation
	47	--
	48	-- Hence, when defining the STAT form, the phases have to be
	49	-- described. If no weight is precisely known, give 1. for all...
	50	-- No phase description will give only one "default" phase
	51	-- For each phase, a typical cycle can be described by its steps.
	52	-- Here too, for no weight precisely known, give 1. for all...
	53	--
	54	-- For executing, activate a STAT to begin count. Give counts of
	55	-- items and cycles for the first phase (for the unique default
	56	-- one if no phasing is described)
	57	-- Else, give count of items and cycles for each new phase.
	58	-- Class methods allow also to set next cycle (given count of
	59	-- items), next step in cycle (if more then one), next item in
	60	-- step.
	61
	62	uses Integer, Real, HSequenceOfInteger, HSequenceOfReal,
	63	CString, HAsciiString, HSequenceOfAsciiString
	64
65	is
66
67	-- -- Description of a STAT form -- --
68
69	Create (title : CString = "") returns STAT;
70	---Purpose : Creates a STAT form. At start, one default phase is defined,
71	-- with one default step. Then, it suffises to start with a
72	-- count of items (and cycles if several) then record items,
73	-- to have a queryable report.
74
75	Create (other : STAT) returns STAT;
76	---Purpose : used when starting
77
78	Internals (me; tit : out HAsciiString; total : out Real;
79	phn : out HSequenceOfAsciiString; phw : out HSequenceOfReal;
80	phdeb, phfin : out HSequenceOfInteger;
81	stw : out HSequenceOfReal);
82	---Purpose : Returns fields in once, without copying them, used for copy
83	-- when starting
84
85	AddPhase (me : in out; weight : Real; name : CString = "");
86	---Purpose : Adds a new phase to the description.
87	-- The first one after Create replaces the default unique one
88
89	AddStep (me : in out; weight : Real = 1);
90	---Purpose : Adds a new step for the last added phase, the default unique
91	-- one if no AddPhase has already been added
92	-- Warning : AddStep before the first AddPhase are cancelled
93
94	Description (me; nbphases : out Integer; total : out Real; title : out CString);
95	---Purpose : Returns global description (cumulated weights of all phases,
96	-- count of phases,1 for default, and title)
97
98	Phase (me; num : Integer;n0step, nbstep : out Integer; weight : out Real; name : out CString);
99	---Purpose : Returns description of a phase, given its rank
100	-- (n0 for first step, count of steps, default gives one;
101	-- weight, name)
102
103	Step (me; num : Integer) returns Real;
104	---Purpose : Returns weight of a Step, related to the cumul given for the
105	-- phase.
106	-- <num> is given by <n0step> + i, i between 1 and <nbsteps>
107	-- (default gives n0step < 0 then weight is one)
108
109	-- -- Running : Filling -- --
110
111	Start (me; items : Integer; cycles : Integer = 1);
112	---Purpose : Starts a STAT on its first phase (or its default one)
113	-- <items> gives the total count of items, <cycles> the count of
114	-- cycles
115	-- If <cycles> is more than one, the first Cycle must then be
116	-- started by NextCycle (NextStep/NextItem are ignored).
117	-- If it is one, NextItem/NextStep can then be called
118
119	StartCount (myclass; items : Integer; title : CString = "");
120	---Purpose : Starts a default STAT, with no phase, no step, ready to just
121	-- count items.
122	-- <items> gives the total count of items
123	-- Hence, NextItem is available to directly count
124
125	NextPhase (myclass; items : Integer; cycles : Integer = 1);
126	---Purpose : Commands to resume the preceeding phase and start a new one
127	-- <items> and <cycles> as for Start, but for this new phase
128	-- Ignored if count of phases is already passed
129	-- If <cycles> is more than one, the first Cycle must then be
130	-- started by NextCycle (NextStep/NextItem are ignored).
131	-- If it is one, NextItem/NextStep can then be called
132
133	SetPhase (myclass; items : Integer; cycles : Integer = 1);
134	---Purpose : Changes the parameters of the phase to start
135	-- To be used before first counting (i.e. just after NextPhase)
136	-- Can be used by an operator which has to reajust counts on run
137
138	NextCycle (myclass; items : Integer);
139	---Purpose : Commands to resume the preceeding cycle and start a new one,
140	-- with a count of items
141	-- Ignored if count of cycles is already passed
142	-- Then, first step is started (or default one)
143	-- NextItem can be called for the first step, or NextStep to pass
144	-- to the next one
145
146	NextStep (myclass);
147	---Purpose : Commands to resume the preceeding step of the cycle
148	-- Ignored if count of steps is already passed
149	-- NextItem can be called for this step, NextStep passes to next
150
151	NextItem (myclass; nbitems : Integer = 1);
152	---Purpose : Commands to add an item in the current step of the current
153	-- cycle of the current phase
154	-- By default, one item per call, can be overpassed
155	-- Ignored if count of items of this cycle is already passed
156
157	End (myclass);
158	---Purpose : Commands to declare the process ended (hence, advancement is
159	-- forced to 100 %)
160
161	-- -- Running : Querying -- --
162
163	Where (myclass; phase : Boolean = Standard_True) returns CString;
164	---Purpose : Returns an identification of the STAT :
165	-- <phase> True (D) : the name of the current phase
166	-- <phase> False : the title of the current STAT
167
168	Percent (myclass; phase : Boolean = Standard_False) returns Integer;
169	---Purpose : Returns the advancement as a percentage :
170	-- <phase> True : inside the current phase
171	-- <phase> False (D) : relative to the whole process
172
173	fields -- used for description, not for running
174
175	thetitle : HAsciiString;
176	thetotal : Real;
177	thephnam : HSequenceOfAsciiString;
178	thephw : HSequenceOfReal;
179	thephdeb : HSequenceOfInteger; -- nums of steps of each phase
180	thephfin : HSequenceOfInteger;
181
182	thestw : HSequenceOfReal;
183
184	end STAT;