src/Message/Message_ProgressIndicator.cdl

   1 -- Created on: 2002-02-20
   2 -- Created by: Andrey BETENEV
   3 -- Copyright (c) 2002-2014 OPEN CASCADE SAS
   4 --
   5 -- This file is part of Open CASCADE Technology software library.
   6 --
   7 -- This library is free software; you can redistribute it and/or modify it under
   8 -- the terms of the GNU Lesser General Public License version 2.1 as published
   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.
  12 --
  13 -- Alternatively, this file may be used under the terms of Open CASCADE
  14 -- commercial license or contractual agreement.
  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 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;