[occt.git] / src / Message / Message_ProgressIndicator.cdl

-- Created on: 2002-02-20
-- Created by: Andrey BETENEV
-- Copyright (c) 2002-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 License 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.

deferred class ProgressIndicator from Message inherits TShared from MMgt

    ---Purpose: Defines abstract interface from program to the "user".
    --          That includes progress indication and user break mechanisms
    --
    --          The interface to progress indicator represents it as a scale 
    --          for each range and step can be defined by the program that uses it.
    --          The scale can be made "infinite", which means it will grow
    --          non-linearly, end of scale will be approached asymptotically at
    --          infinite number of steps. In that case value of scale range 
    --          gives a number of steps corresponding to position at 1/2 of scale.
    --          The current position can be either set directly (in a range from
    --          current position to maximum scale value), or incremented step 
    --          by step.
    --
    --          Progress indication mechanism is adapted for convenient
    --          usage in hiererchical processes that require indication of
    --          progress at several (sub)levels of the process. 
    --          For that purpose, it is possible to create restricted sub-scope of
    --          indication by specifying part of a current scale that is to be 
    --          used by the subprocess.
    --          When subprocess works with progress indicator in the restricted
    --          scope, it has the same interface to a scale, while actually it 
    --          deals only with part of the whole scale. 
    --
    --          NOTE: 
    --             Currently there is no support for concurrent progress 
    --             indicator that could be useful in multithreaded applications.
    --             The main reason for this is that such implementation would be 
    --             too complex regarding forecasted lack of real need for such 
    --             support.
    --             To support this it would require that ProgressScale keep its
    --             own position and take care of incrementing main ProgressIndicator
    --             in destructor. This would also require having cross-references
    --             between nested instances of ProgressScale, ie. potential 
    --             problems with memory management.
    --             In case of need of concurrent progress indicator two things can
    --             be suggested: either creation of single spane with summary number
    --             of steps, or usage of infinite scale.
    --
    --          The user break is implemented as virtual function that might 
    --          return True in case if break signal from the user is obtained.
    --
    --          The derived classes should take care of visualisation of the
    --          progress indicator (e.g. show total position at the graphical bar,
    --          and/or print all scopes in text mode), and for implementation
    --          of user break mechanism (if defined).

uses
    HAsciiString            from TCollection,
    ProgressScale           from Message,
    SequenceOfProgressScale from Message
is

    ---Scope: Initialisations
    
    Initialize returns mutable ProgressIndicator from Message;
    	---Purpose: Constructor, just calls own Reset() (not yet redefined)

    Reset (me: mutable) is virtual;
    	---Purpose: Drops all scopes and sets scale from 0 to 100, step 1
	--          This scale has name "Step"

    ---Scope: Program API
    
    ------------------------------------------------------------------
    -- Management of current scale
    
    SetName (me: mutable; name: CString); 
    	---C++: inline
    SetName (me: mutable; name: HAsciiString from TCollection);
    	---C++: inline
    	---Purpose: Set (optional) name for scale
	
    SetRange (me: mutable; min, max: Real); 
    	---C++: inline
    	---Purpose: Set range for current scale
	
    SetStep (me: mutable; step: Real); 
    	---C++: inline
    	---Purpose: Set step for current scale
	
    SetInfinite (me: mutable; isInf: Boolean = Standard_True); 
    	---C++: inline
    	---Purpose: Set or drop infinite mode for the current scale
    
    SetScale (me: mutable; name: CString; min, max, step: Real; isInf: Boolean = Standard_False); 
    	---C++: inline
    SetScale (me: mutable; min, max, step: Real; isInf: Boolean = Standard_False); 
    	---Purpose: Set all parameters for current scale
    
    GetScale (me; min, max, step: out Real; isInf: out Boolean); 
    	---Purpose: Returns all parameters for current scale
	
    ------------------------------------------------------------------
    -- Management of current progress value
    
    SetValue (me: mutable; val: Real);
    GetValue (me) returns Real;
    	---Purpose: Set and get progress value at current scale
	--          If the value to be set is more than currently set one, or out
        --          of range for the current scale, it is limited by that range
    
    Increment (me: mutable);
    	---C++: inline
    Increment (me: mutable; step: Real);
    	---C++: inline
    	---Purpose: Increment the progress value by the default of specified step
    
    ------------------------------------------------------------------
    -- Management of scopes

    NewScope (me: mutable; name: CString = 0) returns Boolean;
    	---C++: inline
    NewScope (me: mutable; name: HAsciiString from TCollection) returns Boolean;
    	---C++: inline
    NewScope (me: mutable; span: Real; name: CString = 0) returns Boolean;
    	---C++: inline
    NewScope (me: mutable; span: Real; name: HAsciiString from TCollection) returns Boolean;
    	---Purpose: Creates new scope on a part of a current scale from current
	--          position with span either equal to default step, or specified
	--          The scale for the new scope will have specified name and
        --          ranged from 0 to 100 with step 1
	--          Returns False if something is wrong in arguments or in current
        --          position of progress indicator; scope is opened anyway

    EndScope (me: mutable) returns Boolean;
    	---Purpose: Close the current scope and thus return to previous scale
	--          Updates position to be at the end of the closing scope
	--          Returns False if no scope is opened
    
    NextScope (me: mutable; name: CString = 0) returns Boolean;
    	---C++: inline
    NextScope (me: mutable; span: Real; name: CString = 0) returns Boolean;
    	---Purpose: Optimized version of { return EndScope() && NewScope(); }
	
    ------------------------------------------------------------------
    -- User break mechanism
    
    UserBreak (me: mutable) returns Boolean is virtual;
    	---Purpose: Should return True if user has send a break signal.
	--          Default implementation returns False.

    
    ---Scope: Deferred methods to be defined by descendants
    
    Show (me: mutable; force: Boolean = Standard_True) returns Boolean is deferred;
    	---Purpose: Update presentation of the progress indicator
	--          Called when progress position is changed
	--          Flag force is intended for forcing update in case if it is
	--          optimized; all internal calls from ProgressIndicator are 
        --          done with this flag equal to False
    
    ---Scope: Methods to request state of progress indicator (mainly for descendants)
    
    GetPosition (me) returns Real;
    	---C++: inline
    	---Purpose: Returns total progress position on the basic scale 
        --          ranged from 0. to 1.
	
    GetNbScopes (me) returns Integer;
    	---Purpose: Returns current number of opened scopes
	--          This number is always >=1 as top-level scale is always present
    
    GetScope (me; index: Integer) returns ProgressScale from Message;
    	---C++: return const &
    	---Purpose: Returns data for scale of index-th scope 
	--          The first scope is current one, the last is the top-level one
    
fields

    myPosition: Real;
    myScopes: SequenceOfProgressScale from Message;

end ProgressIndicator;
Commit	Line	Data
b311480e	1	-- Created on: 2002-02-20
b311480e	2	-- Created by: Andrey BETENEV
973c2be1	3	-- Copyright (c) 2002-2014 OPEN CASCADE SAS
b311480e	4	--
973c2be1	5	-- This file is part of Open CASCADE Technology software library.
b311480e	6	--
d5f74e42	7	-- This library is free software; you can redistribute it and/or modify it under
d5f74e42	8	-- the terms of the GNU Lesser General Public License version 2.1 as published
973c2be1	9	-- by the Free Software Foundation, with special exception defined in the file
	10	-- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
	11	-- distribution for complete text of the license and disclaimer of any warranty.
b311480e	12	--
973c2be1	13	-- Alternatively, this file may be used under the terms of Open CASCADE
973c2be1	14	-- commercial license or contractual agreement.
7fd59977	15
	16	deferred class ProgressIndicator from Message inherits TShared from MMgt
	17
	18	---Purpose: Defines abstract interface from program to the "user".
	19	-- That includes progress indication and user break mechanisms
	20	--
	21	-- The interface to progress indicator represents it as a scale
	22	-- for each range and step can be defined by the program that uses it.
	23	-- The scale can be made "infinite", which means it will grow
	24	-- non-linearly, end of scale will be approached asymptotically at
	25	-- infinite number of steps. In that case value of scale range
	26	-- gives a number of steps corresponding to position at 1/2 of scale.
	27	-- The current position can be either set directly (in a range from
	28	-- current position to maximum scale value), or incremented step
	29	-- by step.
	30	--
	31	-- Progress indication mechanism is adapted for convenient
	32	-- usage in hiererchical processes that require indication of
	33	-- progress at several (sub)levels of the process.
	34	-- For that purpose, it is possible to create restricted sub-scope of
	35	-- indication by specifying part of a current scale that is to be
	36	-- used by the subprocess.
	37	-- When subprocess works with progress indicator in the restricted
	38	-- scope, it has the same interface to a scale, while actually it
	39	-- deals only with part of the whole scale.
	40	--
	41	-- NOTE:
	42	-- Currently there is no support for concurrent progress
	43	-- indicator that could be useful in multithreaded applications.
	44	-- The main reason for this is that such implementation would be
	45	-- too complex regarding forecasted lack of real need for such
	46	-- support.
	47	-- To support this it would require that ProgressScale keep its
	48	-- own position and take care of incrementing main ProgressIndicator
	49	-- in destructor. This would also require having cross-references
	50	-- between nested instances of ProgressScale, ie. potential
	51	-- problems with memory management.
	52	-- In case of need of concurrent progress indicator two things can
	53	-- be suggested: either creation of single spane with summary number
	54	-- of steps, or usage of infinite scale.
	55	--
	56	-- The user break is implemented as virtual function that might
	57	-- return True in case if break signal from the user is obtained.
	58	--
	59	-- The derived classes should take care of visualisation of the
	60	-- progress indicator (e.g. show total position at the graphical bar,
	61	-- and/or print all scopes in text mode), and for implementation
	62	-- of user break mechanism (if defined).
	63
	64	uses
	65	HAsciiString from TCollection,
	66	ProgressScale from Message,
	67	SequenceOfProgressScale from Message
	68	is
	69
	70	---Scope: Initialisations
	71
	72	Initialize returns mutable ProgressIndicator from Message;
	73	---Purpose: Constructor, just calls own Reset() (not yet redefined)
	74
	75	Reset (me: mutable) is virtual;
	76	---Purpose: Drops all scopes and sets scale from 0 to 100, step 1
	77	-- This scale has name "Step"
	78
79	---Scope: Program API
80
81	------------------------------------------------------------------
82	-- Management of current scale
83
84	SetName (me: mutable; name: CString);
85	---C++: inline
86	SetName (me: mutable; name: HAsciiString from TCollection);
87	---C++: inline
88	---Purpose: Set (optional) name for scale
89
90	SetRange (me: mutable; min, max: Real);
91	---C++: inline
92	---Purpose: Set range for current scale
93
94	SetStep (me: mutable; step: Real);
95	---C++: inline
96	---Purpose: Set step for current scale
97
98	SetInfinite (me: mutable; isInf: Boolean = Standard_True);
99	---C++: inline
100	---Purpose: Set or drop infinite mode for the current scale
101
102	SetScale (me: mutable; name: CString; min, max, step: Real; isInf: Boolean = Standard_False);
103	---C++: inline
104	SetScale (me: mutable; min, max, step: Real; isInf: Boolean = Standard_False);
105	---Purpose: Set all parameters for current scale
106
107	GetScale (me; min, max, step: out Real; isInf: out Boolean);
108	---Purpose: Returns all parameters for current scale
109
110	------------------------------------------------------------------
111	-- Management of current progress value
112
113	SetValue (me: mutable; val: Real);
114	GetValue (me) returns Real;
115	---Purpose: Set and get progress value at current scale
116	-- If the value to be set is more than currently set one, or out
117	-- of range for the current scale, it is limited by that range
118
119	Increment (me: mutable);
120	---C++: inline
121	Increment (me: mutable; step: Real);
122	---C++: inline
123	---Purpose: Increment the progress value by the default of specified step
124
125	------------------------------------------------------------------
126	-- Management of scopes
127
128	NewScope (me: mutable; name: CString = 0) returns Boolean;
129	---C++: inline
130	NewScope (me: mutable; name: HAsciiString from TCollection) returns Boolean;
131	---C++: inline
132	NewScope (me: mutable; span: Real; name: CString = 0) returns Boolean;
133	---C++: inline
134	NewScope (me: mutable; span: Real; name: HAsciiString from TCollection) returns Boolean;
135	---Purpose: Creates new scope on a part of a current scale from current
136	-- position with span either equal to default step, or specified
137	-- The scale for the new scope will have specified name and
138	-- ranged from 0 to 100 with step 1
139	-- Returns False if something is wrong in arguments or in current
140	-- position of progress indicator; scope is opened anyway
141
142	EndScope (me: mutable) returns Boolean;
143	---Purpose: Close the current scope and thus return to previous scale
144	-- Updates position to be at the end of the closing scope
145	-- Returns False if no scope is opened
146
147	NextScope (me: mutable; name: CString = 0) returns Boolean;
148	---C++: inline
149	NextScope (me: mutable; span: Real; name: CString = 0) returns Boolean;
150	---Purpose: Optimized version of { return EndScope() && NewScope(); }
151
152	------------------------------------------------------------------
153	-- User break mechanism
154
155	UserBreak (me: mutable) returns Boolean is virtual;
156	---Purpose: Should return True if user has send a break signal.
157	-- Default implementation returns False.
158
159
160	---Scope: Deferred methods to be defined by descendants
161
162	Show (me: mutable; force: Boolean = Standard_True) returns Boolean is deferred;
163	---Purpose: Update presentation of the progress indicator
164	-- Called when progress position is changed
165	-- Flag force is intended for forcing update in case if it is
166	-- optimized; all internal calls from ProgressIndicator are
167	-- done with this flag equal to False
168
169	---Scope: Methods to request state of progress indicator (mainly for descendants)
170
171	GetPosition (me) returns Real;
172	---C++: inline
173	---Purpose: Returns total progress position on the basic scale
174	-- ranged from 0. to 1.
175
176	GetNbScopes (me) returns Integer;
177	---Purpose: Returns current number of opened scopes
178	-- This number is always >=1 as top-level scale is always present
179
180	GetScope (me; index: Integer) returns ProgressScale from Message;
181	---C++: return const &
182	---Purpose: Returns data for scale of index-th scope
183	-- The first scope is current one, the last is the top-level one
184
185	fields
186
187	myPosition: Real;
188	myScopes: SequenceOfProgressScale from Message;
189
190	end ProgressIndicator;