src/IFSelect/IFSelect_EditForm.cdl

   1 -- Created on: 1998-02-23
   2 -- Created by: Christian CAILLET
   3 -- Copyright (c) 1998-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 EditForm  from IFSelect    inherits TShared
  18
  19     ---Purpose : An EditForm is the way to apply an Editor on an Entity or on
  20     --           the Model
  21     --           It gives read-only or read-write access, with or without undo
  22     --
  23     --           It can be complete (all the values of the Editor are present)
  24     --           or partial (a sub-list of these value are present)
  25     --           Anyway, all references to Number (argument <num>) refer to
  26     --           Number of Value for the Editor
  27     --           While references to Rank are for rank in the EditForm, which
  28     --           may differ if it is not Complete
  29     --           Two methods give the correspondance between this Number and
  30     --           the Rank in the EditForm : RankFromNumber and NumberFromRank
  31     --
  32
  33 uses CString, Transient,
  34      AsciiString from TCollection,
  35      HAsciiString from TCollection,
  36      Array1OfInteger from TColStd,
  37      SequenceOfInteger from TColStd,
  38      Array1OfTransient from TColStd,
  39      HSequenceOfHAsciiString from TColStd,
  40      Messenger from Message,
  41      InterfaceModel from Interface,
  42      Editor from IFSelect, ListEditor from IFSelect
  43
  44 is
  45
  46     Create (editor : Editor; readonly : Boolean; undoable : Boolean;
  47             label : CString = "")  returns EditForm;
  48     ---Purpose : Creates a complete EditForm from an Editor
  49     --           A specific Label can be given
  50
  51     Create (editor : Editor; nums : SequenceOfInteger;
  52             readonly : Boolean; undoable : Boolean;
  53             label : CString = "")  returns EditForm;
  54     ---Purpose : Creates an extracted EditForm from an Editor, limited to
  55     --           the values identified in <nums>
  56     --           A specific Label can be given
  57
  58     EditKeepStatus (me : mutable) returns Boolean;
  59     ---Purpose : Returns and may change the keep status on modif
  60     --           It starts as False
  61     --           If it is True, Apply does not clear modification status
  62     --           and the EditForm can be loaded again, modified value remain
  63     --           and may be applied again
  64     --           Remark that ApplyData does not clear the modification status,
  65     --           a call to ClearEdit does
  66     ---C++ : return &
  67
  68     Label   (me) returns CString;
  69
  70     IsLoaded (me) returns Boolean;
  71     ---Purpose : Tells if the EditForm is loaded now
  72
  73     ClearData (me : mutable);
  74
  75     SetData (me : mutable; ent : Transient; model : InterfaceModel);
  76
  77     SetEntity (me : mutable; ent : Transient);
  78
  79     SetModel  (me : mutable; model : InterfaceModel);
  80
  81     Entity  (me) returns Transient;
  82
  83     Model   (me) returns InterfaceModel;
  84
  85     Editor  (me) returns Editor;
  86
  87     IsComplete (me) returns Boolean;
  88     ---Purpose : Tells if an EditForm is complete or is an extract from Editor
  89
  90     NbValues (me; editable : Boolean) returns Integer;
  91     ---Purpose : Returns the count of values
  92     --           <editable> True : count of editable values, i.e.
  93     --             For a complete EditForm, it is given by the Editor
  94     --             Else, it is the length of the extraction map
  95     --           <editable> False : all the values from the Editor
  96
  97     NumberFromRank (me; rank : Integer) returns Integer;
  98     ---Purpose : Returns the Value Number in the Editor from a given Rank in
  99     --           the EditForm
 100     --           For a complete EditForm, both are equal
 101     --           Else, it is given by the extraction map
 102     --           Returns 0 if <rank> exceeds the count of editable values,
 103
 104     RankFromNumber (me; number : Integer) returns Integer;
 105     ---Purpose : Returns the Rank in the EditForm from a given Number of Value
 106     --           for the Editor
 107     --           For a complete EditForm, both are equal
 108     --           Else, it is given by the extraction map
 109     --           Returns 0 if <number> is not forecast to be edited, or is
 110     --             out of range
 111
 112     NameNumber  (me; name : CString) returns Integer;
 113     ---Purpose : Returns the Value Number in the Editor for a given Name
 114     --           i.e. the true ValueNumber which can be used in various methods
 115     --           of EditForm
 116     --           If it is not complete, for a recorded (in the Editor) but
 117     --           non-loaded name, returns negative value (- number)
 118
 119     NameRank    (me; name : CString) returns Integer;
 120     ---Purpose : Returns the Rank of Value in the EditForm for a given Name
 121     --           i.e. if it is not complete, for a recorded (in the Editor) but
 122     --           non-loaded name, returns 0
 123
 124
 125     LoadDefault  (me : mutable);
 126     ---Purpose : For a read-write undoable EditForm, loads original values
 127     --           from defaults stored in the Editor
 128
 129     LoadData (me : mutable; ent : Transient; model : InterfaceModel)
 130         returns Boolean  is virtual;
 131     ---Purpose : Loads modifications to data
 132     --           Default uses Editor. Can be redefined
 133     --           Remark that <ent> and/or <model> may be null, according to the
 134     --           kind of Editor. Shortcuts are available for these cases, but
 135     --           they finally call LoadData (hence, just ignore non-used args)
 136
 137     LoadEntity (me : mutable; ent : Transient)  returns Boolean;
 138     ---Purpose : Shortcut for LoadData when <model> is not used
 139
 140     LoadModel (me : mutable; model : InterfaceModel)  returns Boolean;
 141     ---Purpose : Shortcut for LoadData when only the model is concerned
 142
 143     LoadData (me : mutable)  returns Boolean;
 144     ---Purpose : Shortcut when both <ent> and <model> are not used
 145     --           (when the Editor works on fully static or global data)
 146
 147
 148
 149     ListEditor (me; num : Integer) returns ListEditor;
 150     ---Purpose : Returns a ListEditor to edit the parameter <num> of the
 151     --           EditForm, if it is a List
 152     --           The Editor created it (by ListEditor) then loads it (by
 153     --             ListValue)
 154     --           For a single parameter, returns a Null Handle ...
 155
 156     LoadValue  (me : mutable; num : Integer; val : HAsciiString);
 157     ---Purpose : Loads an original value (single). Called by the Editor only
 158
 159     LoadList   (me : mutable; num : Integer; list : HSequenceOfHAsciiString);
 160     ---Purpose : Loads an original value as a list. Called by the Editor only
 161
 162     OriginalValue (me; num : Integer) returns HAsciiString;
 163     ---Purpose : From an edited value, returns its ... value (original one)
 164     --           Null means that this value is not defined
 165     --           <num> is for the EditForm, not the Editor
 166     --           It is for a single parameter. For a list, gives a Null Handle
 167
 168     OriginalList  (me; num : Integer) returns HSequenceOfHAsciiString;
 169     ---Purpose : Returns an original value, as a list
 170     --           <num> is for the EditForm, not the Editor
 171     --           For a single parameter, gives a Null Handle
 172
 173
 174     EditedValue (me; num : Integer) returns HAsciiString;
 175     ---Purpose : Returns the Edited (i.e. Modified) Value (string for single)
 176     --           <num> reports to the EditForm
 177     --           If IsModified is False, returns OriginalValue
 178     --           Null with IsModified True : means that this value is not
 179     --             defined or has been removed
 180     --           It is for a single parameter. For a list, gives a Null Handle
 181
 182     EditedList (me; num : Integer) returns HSequenceOfHAsciiString;
 183     ---Purpose : Returns the Edited Value as a list
 184     --           If IsModified is False, returns OriginalValue
 185     --           Null with IsModified True : means that this value is not
 186     --             defined or has been removed
 187     --           For a single parameter, gives a Null Handle
 188
 189     IsModified (me; num : Integer) returns Boolean;
 190     ---Purpose : Tells if a Value (of the EditForm) is modified (directly or
 191     --           through touching by Update)
 192
 193     IsTouched  (me; num : Integer) returns Boolean;
 194     ---Purpose : Tells if a Value (of the EditForm) has been touched, i.e.
 195     --           not modified directly but by the modification of another one
 196     --           (by method Update from the Editor)
 197
 198     Modify  (me : mutable; num : Integer; newval : HAsciiString;
 199              enforce : Boolean = Standard_False) returns Boolean;
 200     ---Purpose : Gives a new value for the item <num> of the EditForm, if
 201     --           it is a single parameter (for a list, just returns False)
 202     --           Null means to Remove it
 203     --           <enforce> True to overpass Protected or Computed Access Mode
 204     --           Calls the method Update from the Editor, which can touch other
 205     --           parameters (see NbTouched)
 206     --           Returns True if well recorded, False if this value is not
 207     --           allowed
 208     --  Warning : Does not apply immediately : will be applied by the method
 209     --           Apply
 210
 211     ModifyList (me : mutable; num : Integer; edited : ListEditor;
 212              enforce : Boolean = Standard_False) returns Boolean;
 213     ---Purpose : Changes the value of an item of the EditForm, if it is a List
 214     --           (else, just returns False)
 215     --           The ListEditor contains the edited values of the list
 216     --           If no edition was recorded, just returns False
 217     --           Calls the method Update from the Editor, which can touch other
 218     --           parameters (see NbTouched)
 219     --           Returns True if well recorded, False if this value is not
 220     --           allowed
 221     --  Warning : Does not apply immediately : will be applied by the method
 222     --           Apply
 223
 224     ModifyListValue (me : mutable; num : Integer; list : HSequenceOfHAsciiString;
 225              enforce : Boolean = Standard_False) returns Boolean;
 226     ---Purpose : As ModifyList but the new value is given as such
 227     --           Creates a ListEditor, Loads it, then calls ModifyList
 228
 229     Touch  (me : mutable; num : Integer; newval : HAsciiString) returns Boolean;
 230     ---Purpose : Gives a new value computed by the Editor, if another parameter
 231     --           commands the value of <num>
 232     --           It is generally the case for a Computed Parameter for instance
 233     --           Increments the counter of touched parameters
 234     --  Warning : it gives no protection for ReadOnly etc... while it is the
 235     --           internal way of touching parameters
 236     --           Does not work (returns False) if <num> is for a list
 237
 238     TouchList (me : mutable; num : Integer; newlist : HSequenceOfHAsciiString)
 239         returns Boolean;
 240     ---Purpose : Acts as Touch but for a list
 241     --           Does not work (returns False) if <num> is for a single param
 242
 243     NbTouched (me) returns Integer;
 244     ---Purpose : Returns the count of parameters touched by the last Modify
 245     --           (apart from the modified parameter itself)
 246     --           Normally it is zero
 247
 248     ClearEdit  (me : mutable; num : Integer = 0);
 249     ---Purpose : Clears modification status : by default all, or one by its
 250     --           numbers (in the Editor)
 251
 252
 253     PrintDefs (me; S : Messenger from Message);
 254     ---Purpose : Prints Definitions, relative to the Editor
 255
 256     PrintValues (me; S : Messenger from Message; what : Integer;
 257                  names : Boolean; alsolist : Boolean = Standard_False);
 258     ---Purpose : Prints Values, according to what and alsolist
 259     --           <names> True : prints Long Names; False : prints Short Names
 260     --           <what> < 0 : prints Original Values (+ flag Modified)
 261     --           <what> > 0 : prints Final Values (+flag Modified)
 262     --           <what> = 0 : prints Modified Values (Original + Edited)
 263     --           <alsolist> False (D) : lists are printed only as their count
 264     --           <alsolist> True : lists are printed for all their items
 265
 266
 267     Apply   (me : mutable)  returns Boolean;
 268     ---Purpose : Applies modifications to own data
 269     --           Calls ApplyData then Clears Status according EditKeepStatus
 270
 271         -- Specific methods : they work with the Editor (which provides the
 272         -- specific behavior) but they can be redefined
 273
 274     Recognize (me) returns Boolean  is virtual;
 275     ---Purpose : Tells if this EditForm can work with its Editor and its actual
 276     --           Data (Entity and Model)
 277     --           Default uses Editor. Can be redefined
 278
 279     ApplyData (me : mutable; ent : Transient; model : InterfaceModel)
 280         returns Boolean  is virtual;
 281     ---Purpose : Applies modifications to data
 282     --           Default uses Editor. Can be redefined
 283
 284     Undo    (me : mutable)  returns Boolean;
 285     ---Purpose : For an undoable EditForm, Applies ... origibal values !
 286     --           and clears modified ones
 287     --           Can be run only once
 288
 289 fields
 290
 291     thecomplete : Boolean;  -- complete ? else see thenums for mapping
 292     theloaded : Boolean;   -- loaded ?
 293     thekeepst : Boolean;   -- to keep edits
 294     thelabel  : AsciiString;
 295     thenums   : Array1OfInteger;
 296     theorigs  : Array1OfTransient;
 297     themodifs : Array1OfTransient;
 298     thestatus : Array1OfInteger;
 299     theeditor : Editor;
 300     theent    : Transient;
 301     themodel  : InterfaceModel;
 302     thetouched : Integer;
 303
 304 end EditForm;