From bf2329a40f5e15edbf410d601685b6b2b174789a Mon Sep 17 00:00:00 2001 From: michael Date: Thu, 19 Jul 2001 15:03:16 +0000 Subject: [PATCH] + initial check in --- docs/typinfo.tex | 532 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 532 insertions(+) create mode 100644 docs/typinfo.tex diff --git a/docs/typinfo.tex b/docs/typinfo.tex new file mode 100644 index 0000000000..b402a82d71 --- /dev/null +++ b/docs/typinfo.tex @@ -0,0 +1,532 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% The TYPINFO unit +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\chapter{The TYPINFO unit} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Constants, Types and variables +\section{Constants, Types and variables} +\subsection{Constants} +The following constants are used in the implementation section of the unit. + +\begin{verbatim} +BooleanIdents: array[Boolean] of String = ('False', 'True'); +DotSep: String = '.'; +\end{verbatim} +The following constants determine the access method for the \var{Stored} +identifier of a property as used in the \var{PropProcs} field of the +\var{TPropInfo} record: +\begin{verbatim} +ptField = 0; +ptStatic = 1; +ptVirtual = 2; +ptConst = 3; +\end{verbatim} +The following typed constants are used for easy selection of property types. +\begin{verbatim} +tkAny = [Low(TTypeKind)..High(TTypeKind)]; +tkMethods = [tkMethod]; +tkProperties = tkAny-tkMethods-[tkUnknown]; +\end{verbatim} + +\subsection{types} +The following pointer types are defined: +\begin{verbatim} +PShortString =^ShortString; +PByte =^Byte; +PWord =^Word; +PLongint =^Longint; +PBoolean =^Boolean; +PSingle =^Single; +PDouble =^Double; +PExtended =^Extended; +PComp =^Comp; +PFixed16 =^Fixed16; +Variant = Pointer; +\end{verbatim} + +The \var{TTypeKind} determines the type of a property: +\begin{verbatim} +TTypeKind = (tkUnknown,tkInteger,tkChar,tkEnumeration, + tkFloat,tkSet,tkMethod,tkSString,tkLString,tkAString, + tkWString,tkVariant,tkArray,tkRecord,tkInterface, + tkClass,tkObject,tkWChar,tkBool,tkInt64,tkQWord, + tkDynArray,tkInterfaceRaw); +tkString = tkSString; +\end{verbatim} +\var{tkString} is an alias that is introduced for Delphi compatibility. + +If the property is and ordinal type, then \var{TTOrdType} determines the +size and sign of the ordinal type: +\begin{verbatim} +TTOrdType = (otSByte,otUByte,otSWord,otUWord,otSLong,otULong); +\end{verbatim} +The size of a float type is determined by \var{TFloatType}: +\begin{verbatim} +TFloatType = (ftSingle,ftDouble,ftExtended,ftComp,ftCurr, + ftFixed16,ftFixed32); +\end{verbatim} +A method property (e.g. an event) can have one of several types: +\begin{verbatim} +TMethodKind = (mkProcedure,mkFunction,mkConstructor,mkDestructor, + mkClassProcedure, mkClassFunction); +\end{verbatim} +The kind of parameter to a method is determined by \var{TParamFlags}: +\begin{verbatim} +TParamFlags = set of (pfVar,pfConst,pfArray,pfAddress,pfReference,pfOut); +\end{verbatim} +Interfaces are described further with \var{TntfFlags}: +\begin{verbatim} +TIntfFlags = set of (ifHasGuid,ifDispInterface,ifDispatch); +\end{verbatim} +The following defines a set of \var{TTypeKind}: +\begin{verbatim} +TTypeKinds = set of TTypeKind; +\end{verbatim} +The \var{TypeInfo} function returns a pointer to a \var{TTypeInfo} record: +\begin{verbatim} +TTypeInfo = record + Kind : TTypeKind; + Name : ShortString; +end; +PTypeInfo = ^TTypeInfo; +PPTypeInfo = ^PTypeInfo; +\end{verbatim} +Note that the Name 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 \var{TTypeInfo} record as a \var{TTypeData} record: +\begin{verbatim} +PTypeData = ^TTypeData; +TTypeData = packed record +case TTypeKind of + tkUnKnown,tkLString,tkWString,tkAString,tkVariant: + (); + tkInteger,tkChar,tkEnumeration,tkWChar: + (OrdType : TTOrdType; + case TTypeKind of + tkInteger,tkChar,tkEnumeration,tkBool,tkWChar : ( + MinValue,MaxValue : Longint; + case TTypeKind of + tkEnumeration: ( + BaseType : PTypeInfo; + NameList : ShortString + ) + ); + tkSet: ( + CompType : PTypeInfo + ) + ); + tkFloat: ( + FloatType : TFloatType + ); + tkSString: + (MaxLength : Byte); + tkClass: + (ClassType : TClass; + ParentInfo : PTypeInfo; + PropCount : SmallInt; + UnitName : ShortString + ); + tkMethod: + (MethodKind : TMethodKind; + ParamCount : Byte; + ParamList : array[0..1023] of Char + {in reality ParamList is a array[1..ParamCount] of: + record + Flags : TParamFlags; + ParamName : ShortString; + TypeName : ShortString; + end; + followed by + ResultType : ShortString} + ); + tkInt64: + (MinInt64Value, MaxInt64Value: Int64); + tkQWord: + (MinQWordValue, MaxQWordValue: QWord); + tkInterface: + (); +end; +\end{verbatim} +If the typeinfo kind is \var{tkClass}, then the property +information follows the \var{UnitName} string, as an array of \var{TPropInfo} records. + +The \var{TPropData} record is not used, but is provided for completeness. +\begin{verbatim} +TPropData = packed record + PropCount : Word; + PropList : record end; +end; +\end{verbatim} +The \var{TPropInfo} record describes one published property of a class: +\begin{verbatim} +PPropInfo = ^TPropInfo; +TPropInfo = packed record + PropType : PTypeInfo; + GetProc : Pointer; + SetProc : Pointer; + StoredProc : Pointer; + Index : Integer; + Default : Longint; + NameIndex : SmallInt; + PropProcs : Byte; + Name : ShortString; +end; +\end{verbatim} +The \var{Name} field is stored not with 255 characters, but with just as many characters +as required to store the name. +\begin{verbatim} +TProcInfoProc = procedure(PropInfo : PPropInfo) of object; +\end{verbatim} +The following pointer and array types are used for typecasts: +\begin{verbatim} +PPropList = ^TPropList; +TPropList = array[0..65535] of PPropInfo; +\end{verbatim} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Functions and procedures +\section{Functions and Procedures} + +\begin{function}{GetTypeData} +\Declaration +Function GetTypeData(TypeInfo : PTypeInfo) : PTypeData; +\Description +\var{GetTypeData} returns a pointer to the \var{TTypeData} record that +follows after the \var{TTypeInfo} record pointed to by \var{TypeInfo}. +It essentially skips the \var{Kind} and \var{Name} fields in the +\var{TTypeInfo} record. +\Errors +None. +\SeeAlso +\end{function} + + +\begin{function}{GetPropInfo} +\Declaration +function GetPropInfo(TypeInfo: PTypeInfo; + const PropName: string) : PPropInfo; +\Description +\var{GetPropInfo} returns a pointer to the \var{TPropInfo} record for a the \var{PropName} +property of a class that has \var{TypeInfo} as class info. +\Errors +If the property \var{PropName} does not exist, \var{Nil} is returned. +\SeeAlso +\seep{GetPropInfos},\seef{GetPropList} +\end{function} + + +\begin{procedure}{GetPropInfos} +\Declaration +Procedure GetPropInfos(TypeInfo: PTypeInfo;PropList: PPropList); +\Description +\var{GetPropInfos} stores pointers to the property information of all published +properties of a class with class info \var{TypeInfo} in the list pointed to by +\var{Proplist}. The \var{PropList} pointer must point to a memory location that +contains enough space to hold all properties of the class and its parent classes. +\Errors +No checks are done to see whether \var{PropList} points to a memory area that +is big enough to hold all pointers. +\SeeAlso +\seef{GetPropInfo},\seef{GetPropList} +\end{procedure} + + +\begin{function}{GetPropList} +\Declaration +Function GetPropList(TypeInfo : PTypeInfo; + TypeKinds : TTypeKinds; + PropList : PPropList) : Integer; +\Description +\var{GetPropList} stores pointers to property information of the class with class +info \var{TypeInfo} for properties of kind \var{TypeKinds} in the list pointed to +by \var{Proplist}. \var{PropList} must contain enough space to hold all properties. + +The function returns the number of pointers that matched the criteria and were stored +in \var{PropList}. +\Errors +No checks are done to see whether \var{PropList} points to a memory area that is big enough +to hold all pointers. +\SeeAlso +\seep{GetPropInfos}, \seef{GetPropInfo} +\end{function} + + +\begin{function}{IsStoredProp} +\Declaration +Function IsStoredProp(Instance : TObject;PropInfo : PPropInfo) : Boolean; +\Description +\var{IsStoredProp} returns \var{True} if the \var{Stored} modifier evaluates +to \var{True} for the property described by \var{PropInfo} for object +\var{Instance}. It returns \var{False} otherwise. If the function returns +\var{True}, this indicates that the property should be written when +streaming the object \var{Instance}. + +If there was no \var{stored} modifier in the declaration of the property, +\var{True} will be returned. +\Errors +No checking is done whether \var{Instance} is non-nil, or whether +\var{PropInfo} describes a valid property of \var{Instance}. +\SeeAlso +\end{function} + + +\begin{function}{GetOrdProp} +\Declaration +Function GetOrdProp(Instance : TObject;PropInfo : PPropInfo) : Longint; +\Description +\var{GetOrdProp} returns the value of the ordinal property described by +\var{PropInfo} for the object \var{Instance}. The value is returned as a +longint, which should be typecasted to the needed type. + +Ordinal properties that can be retrieved include: +\begin{description} +\item[Integers and subranges of integers] The value of the integer will be +returned. +\item[Enumerated types and subranges of enumerated types] The ordinal value +of the enumerated type will be returned. +\item[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. +\end{description} +\Errors +No checking is done whether \var{Instance} is non-nil, or whether +\var{PropInfo} describes a valid ordinal property of \var{Instance} +\SeeAlso +\seep{SetOrdProp}, \seef{GetStrProp}, \seef{GetFloatProp}, +\seef{GetInt64Prop},\seef{GetMethodProp} + +\end{function} + + +\begin{procedure}{SetOrdProp} +\Declaration +Procedure SetOrdProp(Instance : TObject;PropInfo : PPropInfo; Value : Longint); +\Description +\var{SetOrdProp} assigns \var{Value} to the the ordinal property described by +\var{PropInfo} for the object \var{Instance}. + +Ordinal properties that can be set include: +\begin{description} +\item[Integers and subranges of integers] The actual value of the integer must be +passed. +\item[Enumerated types and subranges of enumerated types] The ordinal value +of the enumerated type must be passed. +\item[Subrange types] of integers or enumerated types. Here the ordinal +value must be passed. +\item[Sets] If the base type of the set has less than 31 possible values. +For each possible value; the corresponding bit of \var{Value} must be set. +\end{description} +\Errors +No checking is done whether \var{Instance} is non-nil, or whether +\var{PropInfo} describes a valid ordinal property of \var{Instance}. +No range checking is performed. +\SeeAlso +\seef{GetOrdProp}, \seep{SetStrProp}, \seep{SetFloatProp}, +\seep{SetInt64Prop},\seep{SetMethodProp} +\end{procedure} + + +\begin{function}{GetStrProp} +\Declaration +Function GetStrProp(Instance : TObject;PropInfo : PPropInfo) : Ansistring; +\Description +\var{GetStrProp} returns the value of the string property described by +\var{PropInfo} for object \var{Instance}. +\Errors +No checking is done whether \var{Instance} is non-nil, or whether +\var{PropInfo} describes a valid string property of \var{Instance}. +\SeeAlso +\seep{SetStrProp}, \seef{GetOrdProp}, \seef{GetFloatProp}, +\seef{GetInt64Prop},\seef{GetMethodProp} +\end{function} + +\begin{procedure}{SetStrProp} +\Declaration + procedure SetStrProp(Instance : TObject;PropInfo : PPropInfo; + const Value : Ansistring); +\Description +\var{GetStrProp} assigns \var{Value} to the string property described by +\var{PropInfo} for object \var{Instance}. +\Errors +No checking is done whether \var{Instance} is non-nil, or whether +\var{PropInfo} describes a valid string property of \var{Instance}. +\SeeAlso +\seef{GetStrProp}, \seep{SetOrdProp}, \seep{SetFloatProp}, +\seep{SetInt64Prop},\seep{SetMethodProp} + + +\end{procedure} + +\begin{function}{GetFloatProp} +\Declaration +Function GetFloatProp(Instance : TObject;PropInfo : PPropInfo) : Extended; +\Description +\var{GetFloatProp} returns the value of the float property described by +\var{PropInfo} for the object \var{Instance}. All float types are converted +to extended. +\Errors +No checking is done whether \var{Instance} is non-nil, or whether +\var{PropInfo} describes a valid float property of \var{Instance}. +\SeeAlso +\seep{SetFloatProp}, \seef{GetOrdProp}, \seef{GetStrProp}, +\seef{GetInt64Prop},\seef{GetMethodProp} +\end{function} + + +\begin{procedure}{SetFloatProp} +\Declaration +Procedure SetFloatProp(Instance : TObject; + PropInfo : PPropInfo; + Value : Extended); +\Description +\var{SetFloatProp} assigns \var{Value} to the property described by +\var{PropInfo} for the object \var{Instance}. +\Errors +No checking is done whether \var{Instance} is non-nil, or whether +\var{PropInfo} describes a valid float property of \var{Instance}. +\SeeAlso +\seef{GetFloatProp}, \seep{SetOrdProp}, \seep{SetStrProp}, +\seep{SetInt64Prop},\seep{SetMethodProp} + +\end{procedure} + + +\begin{function}{GetVariantProp} +\Declaration +Function GetVariantProp(Instance : TObject;PropInfo : PPropInfo): Variant; +\Description +Not yet implemented. Provided for Delphi compatibility only. +\Errors +\SeeAlso +\end{function} + + +\begin{procedure}{SetVariantProp} +\Declaration +Procedure SetVariantProp(Instance : TObject; + PropInfo : PPropInfo; + Const Value: Variant); +\Description +Not yet implemented. Provided for Delphi compatibility only. +\Errors +\SeeAlso +\end{procedure} + + +\begin{function}{GetMethodProp} +\Declaration +Function GetMethodProp(Instance : TObject;PropInfo : PPropInfo) : TMethod; +\Description +\var{GetMethodProp} returns the method the property described by +\var{PropInfo} for object \var{Instance}. +The return type \var{TMethod} is defined in the \file{SysUtils} unit as: +\begin{verbatim} +TMethod = packed record + Code, Data: Pointer; +end; +\end{verbatim} +\var{Data} points to the instance of the class with the method \var{Code}. + +\Errors +No checking is done whether \var{Instance} is non-nil, or whether +\var{PropInfo} describes a valid method property of \var{Instance}. +\SeeAlso +\seep{SetMethodProp}, \seef{GetOrdProp}, \seef{GetStrProp}, +\seef{GetFloatProp}, \seef{GetInt64Prop} +\end{function} + + +\begin{procedure}{SetMethodProp} +\Declaration +Procedure SetMethodProp(Instance : TObject;PropInfo : PPropInfo; const Value : TMethod); +\Description +\var{SetMethodProp} assigns \var{Value} to the method the property described +by \var{PropInfo} for object \var{Instance}. + +The type \var{TMethod} of the \var{Value} parameter is defined in the +\file{SysUtils} unit as: +\begin{verbatim} +TMethod = packed record + Code, Data: Pointer; +end; +\end{verbatim} +\var{Data} should point to the instance of the class with the method \var{Code}. + +\Errors +No checking is done whether \var{Instance} is non-nil, or whether +\var{PropInfo} describes a valid method property of \var{Instance}. +\SeeAlso +\seef{GetMethodProp}, \seep{SetOrdProp}, \seep{SetStrProp}, +\seep{SetFloatProp}, \seep{SetInt64Prop} +\end{procedure} + +\begin{function}{GetInt64Prop} +\Declaration +Function GetInt64Prop(Instance: TObject; PropInfo: PPropInfo): Int64; +\Description +\var{GetInt64Prop} returns the value of the property of type +\var{Int64} that is described by \var{PropInfo} for the object +\var{Instance}. + +\Errors +No checking is done whether \var{Instance} is non-nil, or whether +\var{PropInfo} describes a valid \var{Int64} property of \var{Instance}. +\SeeAlso +\seep{SetInt64Prop}, \seef{GetOrdProp}, \seef{GetStrProp}, +\seef{GetFloatProp}, \seef{GetMethodProp} + +\end{function} + +\begin{procedure}{SetInt64Prop} +\Declaration +Procedure SetInt64Prop(Instance: TObject; PropInfo: PPropInfo; const Value: Int64); +\Description +\var{SetInt64Prop} assigns \var{Value} to the property of type +\var{Int64} that is described by \var{PropInfo} for the object +\var{Instance}. +\Errors +No checking is done whether \var{Instance} is non-nil, or whether +\var{PropInfo} describes a valid \var{Int64} property of \var{Instance}. +\SeeAlso +\seef{GetInt64Prop}, \seef{GetMethodProp}, \seep{SetOrdProp}, \seep{SetStrProp}, +\seep{SetFloatProp} +\end{procedure} + +\begin{function}{GetEnumName} +\Declaration +Function GetEnumName(TypeInfo : PTypeInfo;Value : Integer) : string; +\Description +\var{GetEnumName} scans the type information for the enumeration type +desribed by \var{TypeInfo} and returns the name of the enumeration +constant for the element with ordinal value equal to \var{Value}. + +If \var{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 \var{GetOrdProp} to stream a property +of an enumerated type. +\Errors +No check is done whether \var{TypeInfo} points to the type information +for an enumerated type. +\SeeAlso +\seef{GetOrdProp}, \seef{GetEnumValue} +\end{function} + +\begin{function}{GetEnumValue} +\Declaration +Function GetEnumValue(TypeInfo : PTypeInfo;const Name : string) : Integer; +\Description +\var{GetEnumValue} scans the type information for the enumeration type +described by \var{TypeInfor} and returns the ordinal value for the element +in the enumerated type that has identifier \var{Name}. The identifier is +searched in a case-insensitive manner. + +This can be used to set the value of enumerated properties from a stream. +\Errors +If \var{Name} is not found in the list of enumerated values, then -1 is +returned. No check is done whether \var{TypeInfo} points to the type information +for an enumerated type. +\SeeAlso +\seef{GetEnumName}, \seep{SetOrdProp} +\end{function}