path: root/src/IFSelect/IFSelect_EditForm.cdl

-- File:	IFSelect_EditForm.cdl
-- Created:	Mon Feb 23 15:16:04 1998
-- Author:	Christian CAILLET
--		<cky@heliox.paris1.matra-dtv.fr>
---Copyright:	 Matra Datavision 1998


class EditForm  from IFSelect    inherits TShared

    ---Purpose : An EditForm is the way to apply an Editor on an Entity or on
    --           the Model
    --           It gives read-only or read-write access, with or without undo
    --           
    --           It can be complete (all the values of the Editor are present)
    --           or partial (a sub-list of these value are present)
    --           Anyway, all references to Number (argument <num>) refer to
    --           Number of Value for the Editor
    --           While references to Rank are for rank in the EditForm, which
    --           may differ if it is not Complete
    --           Two methods give the correspondance between this Number and
    --           the Rank in the EditForm : RankFromNumber and NumberFromRank
    --           

uses CString, Transient,
     AsciiString from TCollection, 
     HAsciiString from TCollection,
     Array1OfInteger from TColStd, 
     SequenceOfInteger from TColStd,
     Array1OfTransient from TColStd,
     HSequenceOfHAsciiString from TColStd,
     Messenger from Message,
     InterfaceModel from Interface,
     Editor from IFSelect, ListEditor from IFSelect

is

    Create (editor : Editor; readonly : Boolean; undoable : Boolean;
    	    label : CString = "")  returns EditForm;
    ---Purpose : Creates a complete EditForm from an Editor
    --           A specific Label can be given

    Create (editor : Editor; nums : SequenceOfInteger;
    	    readonly : Boolean; undoable : Boolean;
    	    label : CString = "")  returns EditForm;
    ---Purpose : Creates an extracted EditForm from an Editor, limited to
    --           the values identified in <nums>
    --           A specific Label can be given

    EditKeepStatus (me : mutable) returns Boolean;
    ---Purpose : Returns and may change the keep status on modif
    --           It starts as False
    --           If it is True, Apply does not clear modification status
    --           and the EditForm can be loaded again, modified value remain
    --           and may be applied again
    --           Remark that ApplyData does not clear the modification status,
    --           a call to ClearEdit does
    ---C++ : return &

    Label   (me) returns CString;

    IsLoaded (me) returns Boolean;
    ---Purpose : Tells if the EditForm is loaded now

    ClearData (me : mutable);

    SetData (me : mutable; ent : Transient; model : InterfaceModel);

    SetEntity (me : mutable; ent : Transient);

    SetModel  (me : mutable; model : InterfaceModel);

    Entity  (me) returns Transient;

    Model   (me) returns InterfaceModel;

    Editor  (me) returns Editor;

    IsComplete (me) returns Boolean;
    ---Purpose : Tells if an EditForm is complete or is an extract from Editor

    NbValues (me; editable : Boolean) returns Integer;
    ---Purpose : Returns the count of values
    --           <editable> True : count of editable values, i.e.
    --             For a complete EditForm, it is given by the Editor
    --             Else, it is the length of the extraction map
    --           <editable> False : all the values from the Editor

    NumberFromRank (me; rank : Integer) returns Integer;
    ---Purpose : Returns the Value Number in the Editor from a given Rank in
    --           the EditForm
    --           For a complete EditForm, both are equal
    --           Else, it is given by the extraction map
    --           Returns 0 if <rank> exceeds the count of editable values,

    RankFromNumber (me; number : Integer) returns Integer;
    ---Purpose : Returns the Rank in the EditForm from a given Number of Value
    --           for the Editor
    --           For a complete EditForm, both are equal
    --           Else, it is given by the extraction map
    --           Returns 0 if <number> is not forecast to be edited, or is
    --             out of range

    NameNumber  (me; name : CString) returns Integer;
    ---Purpose : Returns the Value Number in the Editor for a given Name
    --           i.e. the true ValueNumber which can be used in various methods
    --           of EditForm
    --           If it is not complete, for a recorded (in the Editor) but
    --           non-loaded name, returns negative value (- number)

    NameRank    (me; name : CString) returns Integer;
    ---Purpose : Returns the Rank of Value in the EditForm for a given Name
    --           i.e. if it is not complete, for a recorded (in the Editor) but
    --           non-loaded name, returns 0


    LoadDefault  (me : mutable);
    ---Purpose : For a read-write undoable EditForm, loads original values
    --           from defaults stored in the Editor

    LoadData (me : mutable; ent : Transient; model : InterfaceModel)
    	returns Boolean  is virtual;
    ---Purpose : Loads modifications to data
    --           Default uses Editor. Can be redefined
    --           Remark that <ent> and/or <model> may be null, according to the
    --           kind of Editor. Shortcuts are available for these cases, but
    --           they finally call LoadData (hence, just ignore non-used args)

    LoadEntity (me : mutable; ent : Transient)  returns Boolean;
    ---Purpose : Shortcut for LoadData when <model> is not used

    LoadModel (me : mutable; model : InterfaceModel)  returns Boolean;
    ---Purpose : Shortcut for LoadData when only the model is concerned

    LoadData (me : mutable)  returns Boolean;
    ---Purpose : Shortcut when both <ent> and <model> are not used
    --           (when the Editor works on fully static or global data)



    ListEditor (me; num : Integer) returns ListEditor;
    ---Purpose : Returns a ListEditor to edit the parameter <num> of the
    --           EditForm, if it is a List
    --           The Editor created it (by ListEditor) then loads it (by
    --             ListValue)
    --           For a single parameter, returns a Null Handle ...

    LoadValue  (me : mutable; num : Integer; val : HAsciiString);
    ---Purpose : Loads an original value (single). Called by the Editor only

    LoadList   (me : mutable; num : Integer; list : HSequenceOfHAsciiString);
    ---Purpose : Loads an original value as a list. Called by the Editor only

    OriginalValue (me; num : Integer) returns HAsciiString;
    ---Purpose : From an edited value, returns its ... value (original one)
    --           Null means that this value is not defined
    --           <num> is for the EditForm, not the Editor
    --           It is for a single parameter. For a list, gives a Null Handle

    OriginalList  (me; num : Integer) returns HSequenceOfHAsciiString;
    ---Purpose : Returns an original value, as a list
    --           <num> is for the EditForm, not the Editor
    --           For a single parameter, gives a Null Handle


    EditedValue (me; num : Integer) returns HAsciiString;
    ---Purpose : Returns the Edited (i.e. Modified) Value (string for single)
    --           <num> reports to the EditForm
    --           If IsModified is False, returns OriginalValue
    --           Null with IsModified True : means that this value is not
    --             defined or has been removed
    --           It is for a single parameter. For a list, gives a Null Handle

    EditedList (me; num : Integer) returns HSequenceOfHAsciiString;
    ---Purpose : Returns the Edited Value as a list
    --           If IsModified is False, returns OriginalValue
    --           Null with IsModified True : means that this value is not
    --             defined or has been removed
    --           For a single parameter, gives a Null Handle

    IsModified (me; num : Integer) returns Boolean;
    ---Purpose : Tells if a Value (of the EditForm) is modified (directly or
    --           through touching by Update)

    IsTouched  (me; num : Integer) returns Boolean;
    ---Purpose : Tells if a Value (of the EditForm) has been touched, i.e.
    --           not modified directly but by the modification of another one
    --           (by method Update from the Editor)

    Modify  (me : mutable; num : Integer; newval : HAsciiString;
    	     enforce : Boolean = Standard_False) returns Boolean;
    ---Purpose : Gives a new value for the item <num> of the EditForm, if
    --           it is a single parameter (for a list, just returns False)
    --           Null means to Remove it
    --           <enforce> True to overpass Protected or Computed Access Mode
    --           Calls the method Update from the Editor, which can touch other
    --           parameters (see NbTouched)
    --           Returns True if well recorded, False if this value is not
    --           allowed
    --  Warning : Does not apply immediately : will be applied by the method
    --           Apply

    ModifyList (me : mutable; num : Integer; edited : ListEditor;
    	     enforce : Boolean = Standard_False) returns Boolean;
    ---Purpose : Changes the value of an item of the EditForm, if it is a List
    --           (else, just returns False)
    --           The ListEditor contains the edited values of the list
    --           If no edition was recorded, just returns False
    --           Calls the method Update from the Editor, which can touch other
    --           parameters (see NbTouched)
    --           Returns True if well recorded, False if this value is not
    --           allowed
    --  Warning : Does not apply immediately : will be applied by the method
    --           Apply

    ModifyListValue (me : mutable; num : Integer; list : HSequenceOfHAsciiString;
    	     enforce : Boolean = Standard_False) returns Boolean;
    ---Purpose : As ModifyList but the new value is given as such
    --           Creates a ListEditor, Loads it, then calls ModifyList

    Touch  (me : mutable; num : Integer; newval : HAsciiString) returns Boolean;
    ---Purpose : Gives a new value computed by the Editor, if another parameter
    --           commands the value of <num>
    --           It is generally the case for a Computed Parameter for instance
    --           Increments the counter of touched parameters
    --  Warning : it gives no protection for ReadOnly etc... while it is the
    --           internal way of touching parameters
    --           Does not work (returns False) if <num> is for a list

    TouchList (me : mutable; num : Integer; newlist : HSequenceOfHAsciiString)
    	returns Boolean;
    ---Purpose : Acts as Touch but for a list
    --           Does not work (returns False) if <num> is for a single param

    NbTouched (me) returns Integer;
    ---Purpose : Returns the count of parameters touched by the last Modify
    --           (apart from the modified parameter itself)
    --           Normally it is zero

    ClearEdit  (me : mutable; num : Integer = 0);
    ---Purpose : Clears modification status : by default all, or one by its
    --           numbers (in the Editor)


    PrintDefs (me; S : Messenger from Message);
    ---Purpose : Prints Definitions, relative to the Editor

    PrintValues (me; S : Messenger from Message; what : Integer;
    	    	 names : Boolean; alsolist : Boolean = Standard_False);
    ---Purpose : Prints Values, according to what and alsolist
    --           <names> True : prints Long Names; False : prints Short Names
    --           <what> < 0 : prints Original Values (+ flag Modified)
    --           <what> > 0 : prints Final Values (+flag Modified)
    --           <what> = 0 : prints Modified Values (Original + Edited)
    --           <alsolist> False (D) : lists are printed only as their count
    --           <alsolist> True : lists are printed for all their items


    Apply   (me : mutable)  returns Boolean;
    ---Purpose : Applies modifications to own data
    --           Calls ApplyData then Clears Status according EditKeepStatus

    	-- Specific methods : they work with the Editor (which provides the
    	-- specific behavior) but they can be redefined

    Recognize (me) returns Boolean  is virtual;
    ---Purpose : Tells if this EditForm can work with its Editor and its actual
    --           Data (Entity and Model)
    --           Default uses Editor. Can be redefined

    ApplyData (me : mutable; ent : Transient; model : InterfaceModel)
    	returns Boolean  is virtual;
    ---Purpose : Applies modifications to data
    --           Default uses Editor. Can be redefined

    Undo    (me : mutable)  returns Boolean;
    ---Purpose : For an undoable EditForm, Applies ... origibal values !
    --           and clears modified ones
    --           Can be run only once

fields

    thecomplete : Boolean;  -- complete ? else see thenums for mapping
    theloaded : Boolean;   -- loaded ?
    thekeepst : Boolean;   -- to keep edits
    thelabel  : AsciiString;
    thenums   : Array1OfInteger;
    theorigs  : Array1OfTransient;
    themodifs : Array1OfTransient;
    thestatus : Array1OfInteger;
    theeditor : Editor;
    theent    : Transient;
    themodel  : InterfaceModel;
    thetouched : Integer;

end EditForm;