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