src/MoniTool/MoniTool_TypedValue.cdl

   1 -- Created on: 1998-02-23
   2 -- Created by: Christian CAILLET
   3 -- Copyright (c) 1998-1999 Matra Datavision
   4 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
   5 --
   6 -- The content of this file is subject to the Open CASCADE Technology Public
   7 -- License Version 6.5 (the "License"). You may not use the content of this file
   8 -- except in compliance with the License. Please obtain a copy of the License
   9 -- at http://www.opencascade.org and read it completely before using this file.
  10 --
  11 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
  12 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
  13 --
  14 -- The Original Code and all software distributed under the License is
  15 -- distributed on an "AS IS" basis, without warranty of any kind, and the
  16 -- Initial Developer hereby disclaims all such warranties, including without
  17 -- limitation, any warranties of merchantability, fitness for a particular
  18 -- purpose or non-infringement. Please see the License for the specific terms
  19 -- and conditions governing the rights and limitations under the License.
  20
  21
  22
  23 class TypedValue  from MoniTool  inherits TShared
  24
  25     ---Purpose : This class allows to dynamically manage .. typed values, i.e.
  26     --           values which have an alphanumeric expression, but with
  27     --           controls. Such as "must be an Integer" or "Enumerative Text"
  28     --           etc
  29     --
  30     --           Hence, a TypedValue brings a specification (type + constraints
  31     --           if any) and a value. Its basic form is a string, it can be
  32     --           specified as integer or real or enumerative string, then
  33     --           queried as such.
  34     --           Its string content, which is a Handle(HAsciiString) can be
  35     --           shared by other data structures, hence gives a direct on line
  36     --           access to its value.
  37
  38 uses CString, Type from Standard,
  39      Messenger from Message,
  40      AsciiString from TCollection, HAsciiString from TCollection,
  41      HArray1OfAsciiString  from TColStd, HSequenceOfAsciiString from TColStd,
  42      DictionaryOfInteger from Dico,     DictionaryOfTransient from Dico,
  43      ValueType from MoniTool,
  44      ValueSatisfies from MoniTool, ValueInterpret from MoniTool
  45
  46 raises ConstructionError
  47
  48 is
  49
  50     Create (name : CString;
  51             type : ValueType from MoniTool = MoniTool_ValueText;
  52             init : CString = "")  returns mutable TypedValue;
  53     ---Purpose : Creates a TypedValue, with a name
  54     --
  55     --           type gives the type of the parameter, default is free text
  56     --           Also available : Integer, Real, Enum, Entity (i.e. Object)
  57     --           More precise specifications, titles, can be given to the
  58     --           TypedValue once created
  59     --
  60     --           init gives an initial value. If it is not given, the
  61     --           TypedValue begins as "not set", its value is empty
  62
  63     Create (other : TypedValue) returns mutable TypedValue;
  64     ---Purpose : Creates a TypedValue from another one, by duplication
  65
  66     Internals (me; interp :  out ValueInterpret; satisf : out ValueSatisfies;
  67                satisname : out CString; enums : out DictionaryOfInteger);
  68     ---Purpose : Access to internal data which have no other access
  69
  70     Name   (me) returns CString;
  71     ---Purpose : Returns the name
  72
  73     ValueType   (me) returns ValueType from MoniTool;
  74     ---Purpose : Returns the type of the value
  75
  76     Definition (me) returns AsciiString from TCollection;
  77     ---Purpose : Returns the Definition
  78     --           By priority, the enforced one, else an automatic one, computed
  79     --           from the specification
  80
  81     SetDefinition (me : mutable; deftext : CString);
  82     ---Purpose : Enforces a Definition
  83
  84     Print  (me; S : Messenger from Message)  is virtual;
  85     ---Purpose : Prints definition, specification, and actual status and value
  86
  87     PrintValue (me; S : Messenger from Message);
  88     ---Purpose : Prints only the Value
  89
  90         -- --    Additional definitions    -- --
  91
  92     AddDef   (me : mutable; initext : CString) returns Boolean;
  93     ---Purpose : Completes the definition of a TypedValue by command <initext>,
  94     --           once created with its type
  95     --           Returns True if done, False if could not be interpreted
  96     --           <initext> may be :
  97     --           imin ival : minimum value for an integer
  98     --           imax ival : maximum value for an integer
  99     --           rmin rval : minimum value for a real
 100     --           rmax rval : maximum value for a real
 101     --           unit name : name of unit
 102     --           ematch i  : enum from integer value i, match required
 103     --           enum   i  : enum from integer value i, match not required
 104     --           eval text : add an enumerative value (increments max by 1)
 105     --           eval ??   : add a non-authorised enum value (to be skipped)
 106     --           tmax   l  : maximum length for a text
 107
 108     SetLabel (me : mutable; label : CString);
 109     ---Purpose : Sets a label, which can then be displayed
 110
 111     Label    (me) returns CString;
 112     ---Purpose : Returns the label, if set; else returns an empty string
 113
 114
 115     SetMaxLength    (me : mutable; max : Integer);
 116     ---Purpose : Sets a maximum length for a text (active only for a free text)
 117
 118     MaxLength    (me) returns Integer;
 119     ---Purpose : Returns the maximum length, 0 if not set
 120
 121     SetIntegerLimit (me : mutable; max : Boolean; val : Integer)
 122     ---Purpose : Sets an Integer limit (included) to <val>, the upper limit
 123     --           if <max> is True, the lower limit if <max> is False
 124         raises ConstructionError;
 125     --           Error for a TypedValue not an Integer
 126
 127     IntegerLimit (me; max : Boolean; val : out Integer) returns Boolean;
 128     ---Purpose : Gives an Integer Limit (upper if <max> True, lower if <max>
 129     --           False). Returns True if this limit is defined, False else
 130     --           (in that case, gives the natural limit for Integer)
 131
 132     SetRealLimit (me : mutable; max : Boolean; val : Real)
 133     ---Purpose : Sets a Real limit (included) to <val>, the upper limit
 134     --           if <max> is True, the lower limit if <max> is False
 135         raises ConstructionError;
 136     --           Error for a TypedValue not a Real
 137
 138     RealLimit (me; max : Boolean; val : out Real) returns Boolean;
 139     ---Purpose : Gives an Real Limit (upper if <max> True, lower if <max>
 140     --           False). Returns True if this limit is defined, False else
 141     --           (in that case, gives the natural limit for Real)
 142
 143     SetUnitDef (me : mutable; def : CString)
 144     ---Purpose : Sets (Clears if <def> empty) a unit definition, as an equation
 145     --           of dimensions. TypedValue just records this definition, does
 146     --           not exploit it, to be done as required by user applications
 147         raises ConstructionError;
 148     --           Error for a TypedValue not a Real
 149
 150     UnitDef    (me) returns CString;
 151     ---Purpose : Returns the recorded unit definition, empty if not set
 152
 153
 154     StartEnum (me : mutable;
 155                start : Integer = 0; match : Boolean = Standard_True)
 156     ---Purpose : For an enumeration, precises the starting value (default 0)
 157     --           and the match condition : if True (D), the string value must
 158     --           match the definition, else it may take another value : in that
 159     --           case, the Integer Value will be  Start - 1.
 160     --           (empty value remains allowed)
 161         raises ConstructionError;
 162     --           Error for a TypedValue not an Enum
 163
 164     AddEnum   (me : mutable; v1,v2,v3,v4,v5,v6,v7,v8,v9,v10 : CString = "")
 165     ---Purpose : Adds enumerative definitions. For more than 10, several calls
 166         raises ConstructionError;
 167     --           Error for a TypedValue not an Enum
 168
 169     AddEnumValue (me : mutable; val : CString; num : Integer)
 170     ---Purpose : Adds an enumeration definition, by its string and numeric
 171     --           values. If it is the first setting for this value, it is
 172     --           recorded as main value. Else, it is recognized as alternate
 173     --           string for this numeric value
 174         raises ConstructionError;
 175     --           Error for a TypedValue not an Enum
 176
 177     EnumDef   (me; startcase, endcase : out Integer; match : out Boolean)
 178         returns Boolean;
 179     ---Purpose : Gives the Enum definitions : start value, end value, match
 180     --           status. Returns True for an Enum, False else.
 181
 182     EnumVal   (me; num : Integer) returns CString;
 183     ---Purpose : Returns the value of an enumerative definition, from its rank
 184     --           Empty string if out of range or not an Enum
 185
 186     EnumCase  (me; val : CString) returns Integer;
 187     ---Purpose : Returns the case number which cooresponds to a string value
 188     --           Works with main and additionnal values
 189     --           Returns (StartEnum - 1) if not OK, -1 if not an Enum
 190
 191     SetObjectType (me : mutable; typ : Type)
 192     ---Purpose : Sets type of which an Object TypedValue must be kind of
 193         raises ConstructionError;
 194     ---Purpose:           Error for a TypedValue not an Object (Entity)
 195
 196     ObjectType    (me) returns Type;
 197     ---Purpose : Returns the type of which an Object TypedValue must be kind of
 198     --           Default is Standard_Transient
 199     --           Null for a TypedValue not an Object
 200
 201     SetInterpret  (me : mutable; func : ValueInterpret);
 202     ---Purpose : Sets a specific Interpret function
 203
 204     HasInterpret  (me) returns Boolean  is virtual;
 205     ---Purpose : Tells if a TypedValue has an Interpret
 206
 207     SetSatisfies  (me : mutable; func : ValueSatisfies; name : CString);
 208     ---Purpose : Sets a specific Satisfies function : it is added to the
 209     --           already defined criteria
 210     --           It must match the form :
 211     --             statisfies (val : HAsciiString) returns Boolean
 212
 213     SatisfiesName (me) returns CString;
 214     ---Purpose : Returns name of specific satisfy, empty string if none
 215
 216         -- --    Value    -- --
 217
 218     IsSetValue   (me) returns Boolean;
 219     ---Purpose : Returns True if the value is set (not empty/not null object)
 220
 221     CStringValue (me) returns CString;
 222     ---Purpose : Returns the value, as a cstring. Empty if not set.
 223
 224     HStringValue (me) returns mutable HAsciiString;
 225     ---Purpose : Returns the value, as a Handle (can then be shared)
 226     --           Null if not defined
 227
 228     Interpret (me; hval : HAsciiString; native : Boolean)
 229         returns HAsciiString  is virtual;
 230     ---Purpose : Interprets a value.
 231     --           <native> True  : returns a native value
 232     --           <native> False : returns a coded  value
 233     --           If the Interpret function is set, calls it
 234     --           Else, for an Enum, Native returns the Text, Coded returns
 235     --             the number
 236     --           STANDARD RETURNS : = hval means no specific interpretation
 237     --            Null means senseless
 238     --           Can also be redefined
 239
 240     Satisfies (me; hval : HAsciiString) returns Boolean  is virtual;
 241     ---Purpose : Returns True if a value statifies the specification
 242     --           (remark : does not apply to Entity : see ObjectType, for this
 243     --           type, the string is just a comment)
 244
 245     ClearValue (me : mutable);
 246     ---Purpose : Clears the recorded Value : it is now unset
 247
 248     SetCStringValue (me : mutable;  val : CString)
 249     ---Purpose : Changes the value. The new one must satisfy the specification
 250         returns Boolean  is virtual;
 251     ---Purpose:           Returns False (and did not set) if the new value
 252     --             does not satisfy the specification
 253     --           Can be redefined to be managed (in a subclass)
 254
 255     SetHStringValue (me : mutable; hval : mutable HAsciiString)
 256     ---Purpose : Forces a new Handle for the Value
 257     --           It can be empty, else (if Type is not free Text), it must
 258     --           satisfy the specification.
 259     --           Not only the value is changed, but also the way it is shared
 260     --           Remark : for Type=Object, this value is not controlled, it can
 261     --           be set as a comment
 262         returns Boolean  is virtual;
 263     ---Purpose:           Returns False (and did not set) if the new value
 264     --             does not satisfy the specification
 265     --           Can be redefined to be managed (in a subclass)
 266
 267     IntegerValue (me) returns Integer;
 268     ---Purpose : Returns the value as integer, i.e. :
 269     --           For type = Integer, the integer itself; 0 if not set
 270     --           For type = Enum, the designated rank (see Enum definition)
 271     --             StartEnum - 1 if not set or not in the definition
 272     --           Else, returns 0
 273
 274     SetIntegerValue (me : mutable; ival : Integer)
 275     ---Purpose : Changes the value as an integer, only for Integer or Enum
 276         returns Boolean  is virtual;
 277     --           Returns False (and did not set) if type is neither Integer
 278     --           nor Enum, or if ival is out of range (if a range is specified)
 279     --           Can be redefined to be managed (in a subclass)
 280
 281     RealValue (me) returns Real;
 282     ---Purpose : Returns the value as real,  for a Real type TypedValue
 283     --           Else, returns 0.
 284
 285     SetRealValue (me : mutable; rval : Real)
 286     ---Purpose : Changes the value as a real, only for Real
 287         returns Boolean  is virtual;
 288     --           Returns False (and did not set) if type is not Real or
 289     --            out of range (if a range is specified)
 290     --           Can be redefined to be managed (in a subclass)
 291
 292     ObjectValue (me) returns any Transient;
 293     ---Purpose : Returns the value as Transient Object, only for Object/Entity
 294     --           Remark that the "HString value" is IGNORED here
 295     --           Null if not set; remains to be casted
 296
 297     GetObjectValue (me; val : out Transient);
 298     ---Purpose : Same as ObjectValue, but avoids DownCast : the receiving
 299     --           variable is directly loaded. It is assumed that it complies
 300     --           with the definition of ObjectType ! Otherwise, big trouble
 301
 302     SetObjectValue (me : mutable; obj : any Transient)
 303         returns Boolean  is virtual;
 304     ---Purpose : Changes the value as Transient Object, only for Object/Entity
 305     --           Returns False if DynamicType does not satisfy ObjectType
 306     --           Can be redefined to be managed (in a subclass)
 307
 308     ObjectTypeName (me) returns CString;
 309     ---Purpose : Returns the type name of the ObjectValue, or an empty string
 310     --           if not set
 311
 312         -- --    Library of TypedValue as Type Definitions,    -- --
 313         --       accessed by definition name
 314         --       It starts with 3 basic types : "Integer" "Real" "Text"
 315
 316     AddLib (myclass; tv : TypedValue; def : CString = "") returns Boolean;
 317     ---Purpose : Adds a TypedValue in the library.
 318     --           It is recorded then will be accessed by its Name
 319     --           Its Definition may be imposed, else it is computed as usual
 320     --           By default it will be accessed by its Definition (string)
 321     --           Returns True if done, False if tv is Null or brings no
 322     --           Definition or <def> not defined
 323     --
 324     --           If a TypedValue was already recorded under this name, it is
 325     --           replaced
 326
 327     Lib (myclass; def : CString) returns TypedValue;
 328     ---Purpose : Returns the TypedValue bound with a given Name
 329     --           Null Handle if none recorded
 330     --           Warning : it is the original, not duplicated
 331
 332     FromLib (myclass; def : CString) returns TypedValue;
 333     ---Purpose : Returns a COPY of the TypedValue bound with a given Name
 334     --           Null Handle if none recorded
 335
 336     LibList (myclass) returns HSequenceOfAsciiString;
 337     ---Purpose : Returns the list of names of items of the Library of Types
 338         -- --    Library of TypedValue as Valued Parameters,    -- --
 339         --       accessed by parameter name
 340         --       for use by management of Static Parameters
 341
 342     Stats (myclass) returns DictionaryOfTransient  is protected;
 343     ---Purpose : Gives the internal library of static values
 344
 345     StaticValue (myclass; name : CString) returns TypedValue;
 346     ---Purpose : Returns a static value from its name, null if unknown
 347
 348 fields
 349
 350     thename   : AsciiString;
 351     thedef    : AsciiString;
 352     thelabel  : AsciiString;
 353     thetype   : ValueType from MoniTool;
 354     theotyp   : Type from Standard;  -- for object
 355
 356     thelims   : Integer;  -- status for integer/enum/real limits
 357     themaxlen : Integer;
 358     theintlow : Integer;
 359     theintup  : Integer;
 360     therealow : Real;
 361     therealup : Real;
 362     theunidef : AsciiString;
 363
 364     theenums  : HArray1OfAsciiString    from TColStd;
 365     theeadds  : DictionaryOfInteger;
 366
 367     theinterp : ValueInterpret;
 368     thesatisf : ValueSatisfies;
 369     thesatisn : AsciiString;
 370
 371     theival   : Integer;
 372     thehval   : HAsciiString from TCollection;
 373     theoval   : Transient;
 374
 375 end TypedValue;