diff --git a/docs/typinfo.xml b/docs/typinfo.xml new file mode 100644 index 0000000000..1ddf9f4a91 --- /dev/null +++ b/docs/typinfo.xml @@ -0,0 +1,1507 @@ + + + + + +The TYPINFO unit + + +

+The TypeInfo unit contains many routines which can be used for +the querying of the Run-Time Type Information (RTTI) which is generated +by the compiler for classes that are compiled under the {$M+} +switch. This information can be used to retrieve or set property values +for published properties for totally unknown classes. In particular, it +can be used to stream classes. The TPersistent class in the +Classes unit is compiled in the {$M+} state and serves +as the base class for all classes that need to be streamed. +

+

+The unit should be compatible to the Delphi 5 unit with the same name. +The only calls that are still missing are the Variant calls, since Free Pascal +does not support the variant type yet. +

+

+The examples in this chapter use a rttiobj file, which contains +an object that has a published property of all supported types. It also +contains some auxiliary routines and definitions. +

+ + + +Examining published property information + +

+Functions for retrieving or examining property information +

+ + + + + + + + + + + +
NameDescription
Getting property type information, With error checking.
Getting property type information, No error checking.
Find property information of a certain kind
Return the declared class of an object property
Get a list of all published properties
Is a property published
Is a property stored
Is a property of a certain kind
Return the type of a property
+ + + + +Getting or setting property values + +

+Functions to set or set a property's value. +

+ + + + + + + + + + + + + + + + + + + + + + +
NameDescription
Return the value of an enumerated type property
Return the value of a float property
Return the value of an Int64 property
Return the value of a procedural type property
Return the value of an object property
Return the value of an ordinal type property
Return the value of a property as a variant
Return the value of a set property
Return the value of a string property
Return the value of a variant property
Set the value of an enumerated type property
Set the value of a float property
Set the value of an Int64 property
Set the value of a procedural type property
Set the value of an object property
Set the value of an ordinal type property
Set the value of a property trhough a variant
Set the value of a set property
Set the value of a string property
Set the value of a variant property
+ + + + +Auxiliary functions + +

+Other typinfo related functions. +

+ + + + + + + +
NameDescription
Get an enumerated type element name
Get ordinal number of an enumerated tye, based on the name.
Skip type name and return a pointer to the type data
Convert a set to its string representation
Convert a string representation of a set to a set
+ + + + + +Names for boolean values + + + +Name separator character + + + +Property acces directly from field + + + +Property acces via static method + + + +Property acces via virtual method + + + +Constant used in acces method + + + +Any property type + + + +Only method properties. (event handlers) + + + +Real properties. (not methods) + + + +Pointer to shortstring + + + +Pointer to byte + + + +Pointer to Word + + + +Pointer to longint + + + +Pointer to boolean + + + +Pointer to single + + + +Pointer to double + + + +Pointer to extended + + + +Pointer to comp + + + +Pointer to Fixed16 + + + +Dummy type. Do not use. + + + +Type of a property. + + + +Alias for the tsSString enumeration value + + + + +Unknown property type. + + + +Integer property. + + + +Char property. + + + +Enumeration type property. + + + +Float property. + + + +Set property. + + + +Method property. + + + +Shortstring property. + + + +Longstring property. + + + +Ansistring property. + + + +Widestring property. + + + +Variant property. + + + +Array property. + + + +Record property. + + + +Interface property. + + + +Class property. + + + +Object property. + + + +Widechar property. + + + +Boolean property. + + + +Int64 property. + + + +QWord property. + + + +Dynamical array property. + + + +Raw interface property. + + + +Size and sign of ordinal property type. + +If the property is and ordinal type, then TTOrdType determines +the size and sign of the ordinal type: + + + + +Signed byte + + + +Unsigned byte + + + +Signed word + + + +Unsigned word + + + +Signed longint + + + +Unsigned longing (Cardinal) + + + +The size of a float type. + + + +Single-sized float + + + +Double-sized float + + + +Extended-size float + + + +Comp-type float + + + +Currency-type float + + + +16-bit float type + + + +32-bit float type. + + + +Method type description + + + +Procedure method. + + + +Function method + + + +Class constructor + + + +Class Desctructor + + + +Class procedure + + + +Class function + + + +The kind of parameter for a method + + + +Parameter passed by reference + + + +Parameter passed as const (reference) + + + +Array parameter + + + +Address is passed + + + +Reference passed + + + +Out (by reference) + + + +Type of interface. + + + +Set of . + + + +Set of . + + + +Interface has GUID identifier + + + +Interface is a dual dispatch interface + + + +Interface is a dispatch interface + + + +Set of enumeration. + + + +Type information record + +

+The TypeInfo function returns a pointer to a TTypeInfo +record. +

+

+Note that the Name field is stored with as much bytes as needed to store the name, +it is not padded to 255 characters. +The type data immediatly follows the TTypeInfo record as a record. +

+ + + + +Type name + + + +Type kind + + + +Pointer to record + + +Pointer to pointer + + + +Pointer to record. + + + +Class properties type data record. + +

+If the typeinfo kind is tkClass, then the property +information follows the UnitName string, as an array of records. +

+ + + + +Property data record + +The TPropData record is not used, but is provided for completeness and +compatibility with Delphi. + + + + +Pointer to record + + + +Record describing one published property of a class + +

+The TPropInfo record describes one published property of a class. +The property information of a class are stored as an array of +TPropInfo records. +

+

+The Name field is stored not with 255 characters, but with just as many characters +as required to store the name. +

+ + + + +Property type + + +Read handler + + +Write handler + + +Procedure pointer for stored keyword. + + +Index for array properties + + +Default value + + +Index for indexed properties + + +Flags describing property procedures. + + +Property name + + + +Property info callback method + + + +Array of property information pointers + + + +Pointer to + + + +Exception raised in case of an error in one of the functions. + + + +Return property information by property name. + +

+FindPropInfo examines the published property information of a class and +returns a pointer to the property information for property PropName. +The class to be examined can be specified in one of two ways: +

+
+
AClass
a class pointer.
+
Instance
an instance of the class to be investigated.
+
+

+If the property does not exist, a EPropertyError exception will be +raised. The function has the same function as the +FindPropInfo function, but returns Nil if the property does not +exist. +

+ + +Specifying an invalid property name in PropName will result in an +EPropertyError exception. + + + + + + + + + + + +Return name of enumeration constant. + +

+GetEnumName scans the type information for the enumeration type +described by TypeInfo and returns the name of the enumeration +constant for the element with ordinal value equal to Value. +

+

+If Value is out of range, the first element of the enumeration type +is returned. The result is lowercased, but this may change in the future. +

+

+This can be used in combination with GetOrdProp to stream a property +of an enumerated type. +

+ + +No check is done to determine whether TypeInfo really points to the +type information for an enumerated type. + + + + + + + + + + +Return the value of an enumeration type property. + +GetEnumProp returns the value of an property of an enumerated type +and returns the name of the enumerated value for the objetc Instance. +The property whose value must be returned can be specified by its property +info in PropInfo or by its name in PropName + + +No check is done to determine whether PropInfo really points to the +property information for an enumerated type. +Specifying an invalid property name in PropName will result in an +EPropertyError exception. + + + + + + + + + + + + + + + + +Get ordinal value for enumerated type by name + +

+GetEnumValue scans the type information for the enumeration type +described by TypeInfo and returns the ordinal value for the element +in the enumerated type that has identifier Name. The identifier is +searched in a case-insensitive manner. +

+

+This can be used to set the value of enumerated properties from a stream. +

+

+For an example, see . +

+ + +If Name is not found in the list of enumerated values, then -1 is +returned. No check is done whether TypeInfo points to the type information +for an enumerated type. + + + + + + + + + +Return value of floating point property + +GetFloatProp returns the value of the float property described by +PropInfo or with name Propname for the object Instance. +All float types are converted +to extended. + + +No checking is done whether Instance is non-nil, or whether +PropInfo describes a valid float property of Instance. +Specifying an invalid property name in PropName will result in an +EPropertyError exception. + + + + + + + + + + + + + + + + +return value of an Int64 property + + +Publishing of Int64 properties is not yet supported by Free Pascal. This +function is provided for Delphi compatibility only at the moment. + +

+GetInt64Prop returns the value of the property of type +Int64 that is described by PropInfo or with name Propname +for the object Instance. +

+ + +No checking is done whether Instance is non-nil, or whether +PropInfo describes a valid Int64 property of Instance. +Specifying an invalid property name in PropName will result in an +EPropertyError exception + + + + + + + + + + + + + + + + +Return value of a method property + +

+GetMethodProp returns the method the property described by +PropInfo or with name Propname for object Instance. +The return type TMethod is defined in the SysUtils unit as: +

+ +TMethod = packed record + Code, Data: Pointer; +end; + +

+Data points to the instance of the class with the method Code. +

+ + +No checking is done whether Instance is non-nil, or whether +PropInfo describes a valid method property of Instance. +Specifying an invalid property name in PropName will result in an +EPropertyError exception. + + + + + + + + + + + + + + + + +Return value of an object-type property. + +

+GetObjectProp returns the object which the property described by +PropInfo with name Propname points to for object Instance. +

+

+If MinClass is specified, then if the object is not descendent of +class MinClass, then Nil is returned. +

+ + +No checking is done whether Instance is non-nil, or whether +PropInfo describes a valid method property of Instance. +Specifying an invalid property name in PropName will result in an +EPropertyError exception. + + + + + + + + + + + + + + + + +Return class of property. + +

+GetObjectPropClass returns the declared class of the property with name +PropName. This may not be the actual class of the property value. +

+

+For an example, see . +

+ + +No checking is done whether Instance is non-nil. +Specifying an invalid property name in PropName will result in an +EPropertyError exception. + + + + + + + + + + + + +Get the value of an ordinal property + +

+GetOrdProp returns the value of the ordinal property described by +PropInfo or with name PropName for the object Instance. +The value is returned as a longint, which should be typecasted to the +needed type. +

+

+Ordinal properties that can be retrieved include: +

+
+
Integers and subranges of integers
+
The value of the integer will be returned.
+
Enumerated types and subranges of enumerated types
+
The ordinal value of the enumerated type will be returned.
+
Sets
+
If the base type of the set has less than 31 possible values. +If a bit is set in the return value, then the corresponding element of the +base ordinal class of the set type must be included in the set. +
+
+ + +No checking is done whether Instance is non-nil, or whether +PropInfo describes a valid ordinal property of Instance +Specifying an invalid property name in PropName will result in an +EPropertyError exception. + + + + + + + + + + + + + + + + +Return property type information, by property name. + +

+GetPropInfo returns a pointer to the TPropInfo record for a the +PropName property of a class. The class to examine can be specified +in one of three ways: +

+
+
Instance
An instance of the class.
+
AClass
A class pointer to the class.
+
TypeInfo
A pointer to the type information of the class.
+
+

+In each of these three ways, if AKinds is specified, if the property +has TypeKind which is not included in Akinds, Nil will be +returned. +

+

+For an example, see most of the other functions. +

+ + +If the property PropName does not exist, Nil is returned. + + + + + + + + + +Return a list of published properties. + +GetPropInfos stores pointers to the property information of all published +properties of a class with class info TypeInfo in the list pointed to by +Proplist. The PropList pointer must point to a memory location that +contains enough space to hold all properties of the class and its parent classes. + + +No checks are done to see whether PropList points to a memory area that +is big enough to hold all pointers. + + + + + + + + + + +Return a list of a certain type of published properties. + +

+GetPropList stores pointers to property information of the class with class +info TypeInfo for properties of kind TypeKinds in the list pointed to +by Proplist. PropList must contain enough space to hold all properties. +

+

+The function returns the number of pointers that matched the criteria and were stored +in PropList. +

+ + +No checks are done to see whether PropList points to a memory area that is big enough +to hold all pointers. + + + + + + + + + + +Get property value as a string. + +Due to missing Variant support, GetPropValue is not yet implemented. +The declaration is provided for compatibility with Delphi. + + + + + + + + +Return the value of a set property. + +

+GetSetProp returns the contents of a set property as a string. +The property to be returned can be specified by it's name in PropName +or by its property information in PropInfo. +

+

+The returned set is a string representation of the elements in the set as +returned by . The Brackets option can be used to +enclose the string representation in square brackets. +

+ + +No checking is done whether Instance is non-nil, or whether +PropInfo describes a valid ordinal property of Instance +Specifying an invalid property name in PropName will result in an +EPropertyError exception. + + + + + + + + + + + + + +Return the value of a string property. + +GetStrProp returns the value of the string property described by +PropInfo or with name PropName for object Instance. + + +No checking is done whether Instance is non-nil, or whether +PropInfo describes a valid string property of Instance. +Specifying an invalid property name in PropName will result in an +EPropertyError exception. + + + + +, + + + + + + + + +Return a pointer to type data, based on type information. + +GetTypeData returns a pointer to the TTypeData record that +follows after the TTypeInfo record pointed to by TypeInfo. +It essentially skips the Kind and Name fields in the +TTypeInfo record. + + +None. + + + + + + +Return the value of a variant property. + +Due to mising Variant support, the GetVariantProp function is not +yet implemented. Provided for Delphi compatibility only. + + + + + + + + + +Check whether a published property exists. + +

+IsPublishedProp returns true if a class has a published property with +name PropName. The class can be specfied in one of two ways: +

+
+
AClass
A class pointer to the class.
+
Instance
An instance of the class.
+
+ + +No checks are done to ensure Instance or AClass are valid +pointers. Specifying an invalid property name in PropName will result +in an EPropertyError exception. + + + + + + + + + + +Check whether a property is stored. + +

+IsStoredProp returns True if the Stored modifier evaluates +to True for the property described by PropInfo or with name +PropName for object Instance. +It returns False otherwise. If the function returns +True, this indicates that the property should be written when +streaming the object Instance. +

+

+If there was no stored modifier in the declaration of the property, +True will be returned. +

+ + +No checking is done whether Instance is non-nil, or whether +PropInfo describes a valid property of Instance. +Specifying an invalid property name in PropName will result in an +EPropertyError exception. + + + + + + + + + + +Check the type of a published property. + +

+PropIsType returns True if the property with name PropName +has type TypeKind. It returns False otherwise. The class to be +examined can be specified in one of two ways: +

+
+
AClass
A class pointer.
+
Instance
An instance of the class.
+
+ + +No checks are done to ensure Instance or AClass are valid +pointers.Specifying an invalid property name in PropName will result +in an EPropertyError exception. + + + + + + + + + + + +Return the type of a property + +

+Proptype returns the type of the property PropName for a class. +The class to be examined can be specified in one of 2 ways: +

+
+
AClass
A class pointer.
+
Instance
An instance of the class.
+
+ + +No checks are done to ensure Instance or AClass are valid +pointers. Specifying an invalid property name in PropName will result +in an EPropertyError exception. + + + + + + + + + + + +Set value of an enumerated-type property + +

+SetEnumProp sets the property described by PropInfo or with name +PropName to Value. Value must be a string with the name +of the enumerate value, i.e. it can be used as an argument to +. +

+

+For an example, see . +

+ + +No checks are done to ensure Instance or PropInfo are valid +pointers. Specifying an invalid property name in PropName will result +in an EPropertyError exception. + + + + + + + + + + + + +Set value of a float property. + +

+SetFloatProp assigns Value to the property described by +PropInfo or with name Propname for the object Instance. +

+

+For an example, see . +

+ + +No checking is done whether Instance is non-nil, or whether +PropInfo describes a valid float property of Instance. +Specifying an invalid property name in PropName will result in an +EPropertyError exception. + + + + +, + + + + + + + + +Set value of a Int64 property + +

+SetInt64Prop assigns Value to the property of type +Int64 that is described by PropInfo or with name Propname +for the object Instance. +

+

+For an example, see . +

+ + +No checking is done whether Instance is non-nil, or whether +PropInfo describes a valid Int64 property of Instance. +Specifying an invalid property name in PropName will result in an +EPropertyError exception. + + + + + + + + + + + +Set the value of a method property + +

+SetMethodProp assigns Value to the method the property described +by PropInfo or with name Propname for object Instance. +

+

+The type TMethod of the Value parameter is defined in the +SysUtils unit as: +

+ +TMethod = packed record + Code, Data: Pointer; +end; + +

+Data should point to the instance of the class with the method Code. +

+

+For an example, see . +

+ + +No checking is done whether Instance is non-nil, or whether +PropInfo describes a valid method property of Instance. +Specifying an invalid property name in PropName will result in an +EPropertyError exception. + + + + + + + + + + + +Set the value of an object-type property. + +

+SetObjectProp assigns Value to the the object property described by +PropInfo or with name Propname for the object Instance. +

+

+For an example, see . +

+ + +No checking is done whether Instance is non-nil, or whether +PropInfo describes a valid method property of Instance. +Specifying an invalid property name in PropName will result in an +EPropertyError exception. + + + + + + + + + + + + + +Set value of an ordinal property + +

+SetOrdProp assigns Value to the the ordinal property described by +PropInfo or with name Propname for the object Instance. +

+

+Ordinal properties that can be set include: +

+
+
Integers and subranges of integers
+
The actual value of the integer must be passed.
+
Enumerated types and subranges of enumerated types
+
The ordinal value of the enumerated type must be passed.
+
Subrange types
+
of integers or enumerated types. Here the ordinal value must be passed.
+
Sets
+
If the base type of the set has less than 31 possible values. +For each possible value; the corresponding bit of Value must be set.
+
+

+For an example, see . +

+ + +No checking is done whether Instance is non-nil, or whether +PropInfo describes a valid ordinal property of Instance. +No range checking is performed. +Specifying an invalid property name in PropName will result in an +EPropertyError exception. + + + + + + + + + + + + +Set property value as variant + +Due to missing Variant support, this function is not yet implemented; +it is provided for Delphi compatibility only. + + + + + + + + +Set value of set-typed property. + +

+SetSetProp sets the property specified by PropInfo or +PropName for object Instance to Value. Value is a +string which contains a comma-separated list of values, each value being a +string-representation of the enumerated value that should be included in +the set. The value should be accepted by the function. +

+

+The value can be formed using the function. +

+

+For an example, see . +

+ + +No checking is done whether Instance is non-nil, or whether +PropInfo describes a valid ordinal property of Instance. +No range checking is performed. +Specifying an invalid property name in PropName will result in an +EPropertyError exception. + + + + + + + + + + + + + + + +Set value of a string property + +

+SetStrProp assigns Value to the string property described by +PropInfo or with name Propname for object Instance. +

+

+For an example, see +

+ + +No checking is done whether Instance is non-nil, or whether +PropInfo describes a valid string property of Instance. +Specifying an invalid property name in PropName will result in an +EPropertyError exception. + + + + +, + + + + + + + +Convert set to a string description + +

+SetToString takes an integer representation of a set (as received e.g. +by GetOrdProp) and turns it into a string representing the elements in +the set, based on the type information found in the PropInfo property +information. By default, the string representation is not surrounded by +square brackets. Setting the Brackets parameter to True will +surround the string representation with brackets. +

+

+The function returns the string representation of the set. +

+ + +No checking is done to see whether PropInfo points to valid property +information. + + + + + + + + + + + +Set value of a variant property + +Due to missing Variant support, this function is not yet implemented. +Provided for Delphi compatibility only. + + + + + + + + + +Convert string description to a set. + +

+StringToSet converts the string representation of a set in Value +to a integer representation of the set, using the property information found +in PropInfo. This property information should point to the property +information of a set property. The function returns the integer +representation of the set. (i.e, the set value, typecast to an integer) +

+

+The string representation can be surrounded with square brackets, and must +consist of the names of the elements of the base type of the set. The base +type of the set should be an enumerated type. The elements should be +separated by commas, and may be surrounded by spaces. +each of the names will be fed to the function. +

+

+For an example, see . +

+ + +No checking is done to see whether PropInfo points to valid property +information. If a wrong name is given for an enumerated value, then an +EPropertyError will be raised. + + + + + + + + + + +