From 4884766b35e45bc3fabc284bdeff1beb329c727b Mon Sep 17 00:00:00 2001 From: dsiders Date: Thu, 13 Apr 2023 23:55:02 +0100 Subject: [PATCH] Docs: LCL/lresources. Updates topic content for changes in 9e78f5ab. * Updates content in additional topics. * Removes verbose visibility comments. --- docs/xml/lcl/lresources.xml | 1248 +++++++++++++++-------------------- 1 file changed, 529 insertions(+), 719 deletions(-) diff --git a/docs/xml/lcl/lresources.xml b/docs/xml/lcl/lresources.xml index 6add965c6d..4cc3251a2f 100644 --- a/docs/xml/lcl/lresources.xml +++ b/docs/xml/lcl/lresources.xml @@ -14,8 +14,8 @@ used to stream components.

lresources.pp maintains and stores all standard Lazarus -resources in the global LazarusResources list and +resources in the global +LazarusResources list and provides methods and types for component streaming.

@@ -56,7 +56,6 @@ This file is part of the Lazarus Component Library (LCL). - Text of the "automatically generated..." warning in resource files. @@ -64,7 +63,7 @@ Text of the "automatically generated..." warning in resource files. - + Signature for a the version of the TFiler instance used to read or write @@ -73,37 +72,35 @@ value using a Lazarus Resource Stream (LRS file). - + Describes a Lazarus resource stored in TLResourceList. - Name for the Lazarus resource. - The resource type, always uppercase. - The value for the resource. - + Container class used for Lazarus resource descriptions. - + + Member with the list for resource descriptions. @@ -111,19 +108,19 @@ value using a Lazarus Resource Stream (LRS file). - + List used to MergeSort resources in the list. - + The number of resource descriptions in the sorted list. - + Returns the index of the named resource, or -1 if not found. @@ -131,7 +128,6 @@ value using a Lazarus Resource Stream (LRS file). The list is sorted, if required.

- @@ -142,28 +138,23 @@ Ordinal position for the named resource in the list, or -1 when not found. Name of the resource to locate in the list of descriptions. - + - - - - - - - + + + + Sorts the list by resource name. - - + Implements a MergeSort for the resource descriptions in the list. - @@ -178,11 +169,10 @@ Implements a MergeSort for the resource descriptions in the list. - + -MergeSort merge part. +Performs the merge portion of the MergeSort method. - @@ -200,7 +190,7 @@ Implements a MergeSort for the resource descriptions in the list. - + Constructor for the class instance. @@ -211,7 +201,7 @@ and sets the default values for internal members. - + Destructor for the class instance. @@ -222,7 +212,7 @@ class instance. - + Adds a resource description to the list with the specified values. @@ -232,7 +222,6 @@ Adds a resource description to the list with the specified values. ValueType is stored in uppercase.

- @@ -247,33 +236,39 @@ ValueType is stored in uppercase. An array with the String values for the type. - + Returns the resource in the list with the given name and type. - - + +TLResource instance for the resource found with the specified name and value +type. + - + +Name of the resource to locate in the list. + -Should be uppercase, if present. + +Type name for the resource to locate in the method. Should be uppercase, if +present. + - + Gets the number of resource descriptions in the list. - The number of resource descriptions in the list. - + Provides Indexed access to the resource descriptions in the list. @@ -284,22 +279,22 @@ Provides Indexed access to the resource descriptions in the list. - + Helper class for streaming resources (read only). - - + + - + Resource in FPC format. - + Initializes the resource descriptor. @@ -317,11 +312,11 @@ The descriptor must already exist. The resource type, can be Nil. - + + Creates an resource stream for a named resource. - @@ -330,11 +325,10 @@ The descriptor must already exist. The resource type, can be Nil. - + Creates an resource stream for a resource ID. - @@ -343,11 +337,10 @@ The descriptor must already exist. The resource type. - + Creates an resource stream from an resource descriptor. - @@ -356,7 +349,7 @@ The descriptor must already exist. - + Destructor for the class instance. @@ -367,7 +360,7 @@ are used for the platform. Calls the inherited method prior to exit. - + Raises an error on an attempt to write to the stream. @@ -390,13 +383,13 @@ SCantWriteResourceStreamError. - + The resource descriptor, owned by the global resource list. - + Abstract base class for translators used in the LCL. @@ -418,7 +411,8 @@ class like TUpdateTranslator, TDefaultTranslator, or TPOTranslator - + + Specifies a method used to translate a String property. @@ -456,7 +450,7 @@ Persistent object with the property value translated in the method. Variable parameter where the translated value for the property is returned. - + Variable with the default translator used in CreateLRSReader. @@ -471,7 +465,7 @@ The value for the variable is assigned when SetDefaultLang is called. SetDefaultLang - + Stack item type for the nested resource reader/writer. @@ -489,7 +483,7 @@ The value for the variable is assigned when SetDefaultLang is called. - + Stack item for the nested resource reader. @@ -497,40 +491,40 @@ Stack item for the nested resource reader. - + Name for the item on the LRS Reader Object stack. - + Identifies the type for the stack item. - + - + The number of contained collections, needing an EndList. - + - + - + Reader for resource streams. @@ -538,74 +532,71 @@ Stack item for the nested resource reader. Uses an stack for reading nested objects.

- - + + - + The input stream buffer. - + Size of the input buffer. - + Current position in the input buffer. - + The number of bytes in the buffer. - + The object stack. - + - + The Length of the allocated stack. - + - + Skip the property name, then the property value. - - + Skips until the next empty string. - - + Push a new resource item. - @@ -620,7 +611,7 @@ Uses an stack for reading nested objects. The number of contained lists, which need an EndList. - + Pop an item, or decrement its PushCount. @@ -628,85 +619,75 @@ Uses an stack for reading nested objects. Called on EndList (vaNull) encountered

- - + Destroys the stack, during reader destruction. - - + Reads the 1-byte value type. - - + Terminate reading a Component list (properties or children). - - + Reads an 4 byte integer value. - - + - - The input stream. - The stream buffer size to allocate. - + - + Peek the next byte (value type indicator). - - + Reads the next ValueType. Pops or pushes a stack item if required (for list or collection). - - + Reads the filer signature from the input. @@ -715,11 +696,10 @@ EReadError 'Invalid Filer Signature' on filer signature mismatch. - + - @@ -734,31 +714,28 @@ EReadError 'Invalid Filer Signature' on filer signature mismatch. - + - - + Returns the qualified current item name. - - + Read a number of bytes from the input stream. - @@ -767,58 +744,53 @@ EReadError 'Invalid Filer Signature' on filer signature mismatch. - + Reads binary data, stored with a Length prefix. - - + Reads an Extended value (10 Bytes). The result may have less bytes, when Extended is not a 10 byte value. - - + Reads an Single value (4 bytes). - - + Reads an Currency value (8 bytes). - - + Reads an Date value (8 bytes). - - + Reads an identifier, maybe a name or a standard key (which is not stored). @@ -835,51 +807,46 @@ stored). vaTrue, vaNull for an standard string. - + - - + - - + - - + - - + Reads enum member names, until an empty string is read. - @@ -888,21 +855,19 @@ vaTrue, vaNull for an standard string. The expected set type. - + Reads an ShortString. - - + - @@ -911,59 +876,55 @@ vaTrue, vaNull for an standard string. - + - - + - - + Skips an entire Component. - If True: skip prefix, component class name and component object name. - + Skips the next value. - - + The input stream. - + The root component reader. - + - + Tracking what already has been stored or written. @@ -980,7 +941,7 @@ header saved on stack, not yet written to stream, waiting for data. header written to stream, data written. - + Stack item for the nested resource writer. @@ -988,130 +949,129 @@ writer. - + - + - + - + waiting for this number of Pops. - + Index in a collection or list. - + - + - + - + - + - + - + Object writer for Lazarus Resource Streams. The TLRSObjectWriter can find empty entries and omit writing them to stream. - - + + - + - + - + - + - + - + - + - + - + - + - @@ -1129,42 +1089,37 @@ The TLRSObjectWriter can find empty entries and omit writing them to stream. - + - - + - - + - - + - - + - @@ -1173,474 +1128,399 @@ The TLRSObjectWriter can find empty entries and omit writing them to stream. - + + - - + - - - + - - - + - - - + - - - + - - - + - - - + - - - + - - - + - - + - - + Writes multiples words (WideChar) with reversed byte order. - - - - + - - - + + - - - - + - + - - + - - - - - + - - + - - + - - - + - - + - - + - - - - + - - - - + - - - + - - - + - - - + - - + - - - + - - - + - - - + - - - + - - - - + - - - + - - + - - + - + - + - + - + - + - + - + - + - + + - + - + - - - - - - - + + + - - - - - - - + + + - - - - - - - + + + @@ -1649,31 +1529,20 @@ The TLRSObjectWriter can find empty entries and omit writing them to stream. - + - - - - - - - + + + - - - - - - - + + + - - - - - - - + + + + Constructor for the class instance. @@ -1683,7 +1552,7 @@ Allocates the internal list used to store values in the Data property. - + Destructor for the class instance. @@ -1694,7 +1563,7 @@ method prior to exit. - + Removes items stored in the Data property. @@ -1705,7 +1574,7 @@ Data to be freed. - + Sort the items by LFM or LRS position. @@ -1714,7 +1583,7 @@ Data to be freed. True for sorting by LFM position. - + Searches for an item by LFM or LRS position. @@ -1729,7 +1598,7 @@ Data to be freed. True for searching an LFM position. - + Find a random item within an position range. @@ -1747,7 +1616,7 @@ Data to be freed. True for searching LFM positions. - + Change the position of an item within the given position range. @@ -1766,7 +1635,7 @@ Data to be freed. True for using LFM positions. - + Adds a new item to the Data property using the specified positions and @@ -1784,7 +1653,7 @@ pointer to the item data. - + Indexed access to the LFM positions. @@ -1793,7 +1662,7 @@ pointer to the item data. - + Indexed access to the LRS positions. @@ -1802,7 +1671,7 @@ pointer to the item data. - + Indexed access to the Data pointers. @@ -1812,60 +1681,66 @@ pointer to the item data. - + - + Parser for identifiers, and string and number literals.

Use to get the next token. The token type also is available in Token. -

+

+

Allowed whitespace is newline (CR,LF), tab and space. -

+

+

Allowed identifiers consist of ASCII letters, digits or underscore. -

+

+

Strings are a sequence of quoted strings or #nn characters. -

+

+

Numbers are parsed as integer or floating point values, with toFloat values subdivided into number, single, date or currency, according to FloatType. -

+

+

All other characters are returned literally.

- + + The input stream. - + The allocated buffer. - + Number of valid chars (bytes) in the buffer. - + Current position (index) in the buffer. - + Buffer-relative begin of the current line. @@ -1873,23 +1748,23 @@ All other characters are returned literally. - + - + True when reached the end of the input stream. - + Holds the last parsed token text. - + The name of a token, maybe the Token character itself. @@ -1901,25 +1776,25 @@ All other characters are returned literally. - + Fills the buffer from the input stream. - + Skips to the next non-null character. - + Add the current character to the token string. - + True when the current character is a digit. @@ -1928,7 +1803,7 @@ All other characters are returned literally. - + True when the current character is a hex digit. @@ -1937,7 +1812,7 @@ All other characters are returned literally. - + True when the current character is an ASCII character (or underscore). @@ -1950,7 +1825,7 @@ True when the current character is an ASCII character (or underscore). - + True when the current character is a digit or IsAlpha. @@ -1959,7 +1834,7 @@ True when the current character is an ASCII character (or underscore). - + Returns the value of a hex digit. @@ -1971,7 +1846,7 @@ True when the current character is an ASCII character (or underscore). - + Parses and returns an identifier. @@ -1983,44 +1858,44 @@ identifier. - + Skip CR/LF, adjust SourceLine. - + Skip space and tab chars. - + Skip all whitespace characters. - + Marks end of input reached (fEofReached). - + Parse an identifier. - + Parse a number, recognizing trailing floating point format specifiers. - + Parse a hex number, prefix the token string with '$'. @@ -2029,7 +1904,7 @@ recognizing trailing floating point format specifiers. EParserError when no valid hex digit was found. - + Parse an quoted string, excluding the leading and trailing quotes. @@ -2042,7 +1917,7 @@ Parse an quoted string, excluding the leading and trailing quotes. - + Parse an decimal Unicode codepoint, return it as an UTF-8 string. @@ -2056,36 +1931,39 @@ Parse an decimal Unicode codepoint, return it as an UTF-8 string. Is set to False on a non-ASCII character. - + Parses a string literal.

The string can consist of quoted strings and Unicode codepoints. Surrounding quote characters are removed. -

+

+

The result is stored in fLastTokenStr, in UTF-8 encoding. -

+

+

The resulting token is toString for all-ASCII strings, else toWString.

- + Tries to parse a negative number, or a single '-' character. - + Sets Token to the unrecognized character (no error). - + + Constructor for the class instance. @@ -2106,7 +1984,7 @@ the buffered values. Stream with the values parser in the class. - + Destructor for the class instance. @@ -2119,7 +1997,7 @@ the memory allocated for the internal buffer in the class instance. - + Asserts that Token is of the expected type. @@ -2130,7 +2008,7 @@ the memory allocated for the internal buffer in the class instance. The expected token type. - + Asserts that the given name was parsed (case insensitive). @@ -2142,7 +2020,7 @@ the memory allocated for the internal buffer in the class instance. The expected identifier. - + Raises an EParserError with the given message. @@ -2152,7 +2030,7 @@ the memory allocated for the internal buffer in the class instance. The message text. - + Raises an EParserError with the formatted message. @@ -2165,7 +2043,7 @@ the memory allocated for the internal buffer in the class instance. The arguments to be formatted. - + Raises an EParserError with the given message, adding source position information. @@ -2176,25 +2054,27 @@ information. - + Writes an hex value into the output stream.

The hex digits must occur in pairs, for every byte. -

+

+

The binary bytes are written in input order (highest first).

-EParserError on unpaired hex digits. + +EParserError on unpaired hex digits. The output stream. - + Parses the next token. @@ -2203,7 +2083,7 @@ The binary bytes are written in input order (highest first). The token type. - + Returns the current position in the input stream. @@ -2212,7 +2092,7 @@ The binary bytes are written in input order (highest first). - + Parses an (possibly) qualified identifier, after a symbol has been parsed. @@ -2225,7 +2105,7 @@ Parses an (possibly) qualified identifier, after a symbol has been parsed. - + Returns the binary value of a floating point number. @@ -2236,7 +2116,7 @@ Parses an (possibly) qualified identifier, after a symbol has been parsed. - + Returns the binary value of an integral number. @@ -2245,7 +2125,7 @@ Parses an (possibly) qualified identifier, after a symbol has been parsed. - + Returns the last parsed token as an string. @@ -2255,7 +2135,7 @@ Parses an (possibly) qualified identifier, after a symbol has been parsed. - + Compares the parsed symbol with the given string (case-insensitive). @@ -2268,7 +2148,7 @@ Parses an (possibly) qualified identifier, after a symbol has been parsed. - + The type of the parsed floating point number. (number, date...). @@ -2276,14 +2156,14 @@ The type of the parsed floating point number. (number, date...). - + The current line number in the input stream. - + The current column number in the source line. @@ -2293,16 +2173,16 @@ The type of the parsed floating point number. (number, date...). - + The last parsed token type. - + -A queue to stream components, used for multithreading or network. +A queue to stream components, used for multi-threading or network.

@@ -2316,13 +2196,15 @@ TCustomLazComponentQueue tells you, if a whole component has arrived. - + + - + + Member with the dynamic storage for the queue.. - + Reads the component size and the length for the size value. @@ -2339,7 +2221,8 @@ False if there is not enough storage in the queue for the component size. Number of bytes needed for the component size value. - + + Constructor for the class instance. @@ -2352,7 +2235,7 @@ Allocates resources needed for the internal queue storage. Owner of the class instance. - + Destructor for the class instance. @@ -2363,13 +2246,12 @@ Frees resources allocated to the internal queue storage. - Clears all values in the internal queue storage. - + Pushes values in Buffer onto the internal storage queue. @@ -2386,7 +2268,7 @@ Untyped buffer with values pushed onto the internal queue storage. Number of bytes in Buffer. - + Copies the specified number of bytes from the stream and pushes the values @@ -2404,7 +2286,7 @@ onto the queue. - + Determines whether the queue contains the entire contents of the component at @@ -2416,7 +2298,7 @@ the top of the queue. - + Reads a component from the queue and sets it owner. @@ -2431,7 +2313,7 @@ the top of the queue. - + Converts a component to binary format with a leading size information (using @@ -2446,7 +2328,7 @@ WriteLRSInt64MB). - + Event handler signalled to get the class type for the specified class name in @@ -2455,23 +2337,24 @@ a TReader instance. - + Publishes property from the ancestor class. - + + Published Name for the component queue. - + Published event handler used to get the class type for a give class name. - + Contains information about a property omitted from LCL component streaming. @@ -2486,33 +2369,33 @@ RegisterPropertyToSkip routine is called. - + Class type for the persistent object with the omitted property. - + Name for the omitted property. - + A note about the omitted property. - + Help keyword for the omitted property. - + - + Implements a list used to store properties which are skipped during LCL @@ -2521,31 +2404,17 @@ streaming. - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + Handles a notification action when the specified Pointer is added to or @@ -2560,7 +2429,7 @@ removed from the list. - + Determines if the specified property type and name exists and is handled in @@ -2587,7 +2456,8 @@ the list. - + + Gets the ordinal position in the list where the property type and name is @@ -2608,7 +2478,7 @@ stored. Class type for the property to located in the list. - + Adds the specified property type and name to the list when not already @@ -2634,7 +2504,7 @@ Ordinal position in the list where the skipped property was found or stored. Help keyword for the skipped property. - + Provides indexed access to skipped properties in the list by their ordinal @@ -2652,23 +2522,25 @@ the property value ensures the inherited Get or Put methods are called. Ordinal position for the indexed property value. - + + + - + The list with all of the loaded standard resources. @@ -2676,7 +2548,7 @@ the property value ensures the inherited Get or Put methods are called. - + Unit global variable with all of the registered skipped properties. @@ -2684,23 +2556,22 @@ Unit global variable with all of the registered skipped properties. - + Class type for Lazarus Object Reader instances. - + Class type for Lazarus Object Writer instances. - + - @@ -2712,11 +2583,10 @@ Unit global variable with all of the registered skipped properties. - + - @@ -2728,11 +2598,10 @@ Unit global variable with all of the registered skipped properties. - + - @@ -2744,11 +2613,10 @@ Unit global variable with all of the registered skipped properties. - + - @@ -2760,11 +2628,10 @@ Unit global variable with all of the registered skipped properties. - + - @@ -2776,11 +2643,10 @@ Unit global variable with all of the registered skipped properties. - + - @@ -2795,11 +2661,10 @@ Unit global variable with all of the registered skipped properties. - + - @@ -2808,11 +2673,10 @@ Unit global variable with all of the registered skipped properties. - + - @@ -2833,11 +2697,10 @@ Unit global variable with all of the registered skipped properties. - + - @@ -2846,11 +2709,10 @@ Unit global variable with all of the registered skipped properties. - + - @@ -2868,11 +2730,10 @@ Unit global variable with all of the registered skipped properties. - + - @@ -2884,11 +2745,10 @@ Unit global variable with all of the registered skipped properties. - + - @@ -2909,11 +2769,10 @@ Unit global variable with all of the registered skipped properties. - + - @@ -2925,11 +2784,10 @@ Unit global variable with all of the registered skipped properties. - + - @@ -2941,7 +2799,7 @@ Unit global variable with all of the registered skipped properties. - + @@ -2951,157 +2809,194 @@ lines. It needs huge amounts of memory and becomes very slow. Therefore big files are split into several strings.

- - - - - - + - - - - + - - - - - + - - - - + - - + +

+ReadLFMHeader is an overloaded procedure used to read the header +for the LFM resource. The overloaded variants allow the LFM content to be read +from either a TStream instance or a string value. +

+

+Values for the LFM resource type (optional), component name, and class name +are returned in the corresponding output variables. +

+

+ReadLFMHeader is used to implement portions of the Lazarus IDE like the form +editor, project inspector, and source code file manager. +

+ + +Modified in LCL 2.4 to support use of unit name as a name space for classes in +a LFM resource. + - + +TStream instance with the LFM content read in the routine. + - + +Output variable which returns the type token for a resource item. + - + +Output variable which returns the component name token for a resource item. + - + +Output variable which returns the class name token for a resource item. Allows +unit name to be included as a name space for the class. + - + +String type with the LFM content read in the routine. + - + - + +Reads the LFM header from the specified file name. + - - + + + - + +Returns True if the resource header is successfully read from the file +and the LFM class name contains a non-empty value. + - + +File with the LFM content read in the routine. + - + +Returns the resource type in the LFM header. Normally 'object'. + - + +Returns the component name read from the LFM header. Like 'Form1'. + - + +Returns the class name read from the LFM header. Like 'TForm1', but may also +include a unit name space such as 'ns.unit2/TForm2'. + - + - - - - - + - + +Represent the LRS stream format offered as the original content for conversion +routines like LRSObjectToText and LRSObjectResToText. + - + + + + + + - + +Format for the LRS stream is unknown. + - + +LRS stream contains binary content. + - + +LRS stream contains the text content. + - + - @@ -3113,79 +3008,64 @@ files are split into several strings. - + - - - - + - - - - - + - - - - + - - - - - + - @@ -3194,11 +3074,10 @@ files are split into several strings. - + - @@ -3207,11 +3086,10 @@ files are split into several strings. - + - @@ -3226,71 +3104,58 @@ files are split into several strings. - + - - - - + - - - - + - - - - + - - - - + - @@ -3299,11 +3164,10 @@ files are split into several strings. - + - @@ -3312,11 +3176,10 @@ files are split into several strings. - + - @@ -3325,11 +3188,10 @@ files are split into several strings. - + - @@ -3338,116 +3200,94 @@ files are split into several strings. - + - - - - + - - - - + - - - - + - - - - + - - - - + - - - - + - - - - + - @@ -3456,11 +3296,10 @@ files are split into several strings. - + - @@ -3469,26 +3308,22 @@ files are split into several strings. - + - - - - + - @@ -3497,11 +3332,10 @@ files are split into several strings. - + - @@ -3510,11 +3344,10 @@ files are split into several strings. - + - @@ -3523,116 +3356,109 @@ files are split into several strings. - + - - - - + +Writes a Word value to the specified resource stream. + + +

+For platforms where FPC_LITTLE_ENDIAN is defined, the Write method in the +Stream is called write the bytes in the word value. For Big Endian platforms, +the WriteLRSReversedWord routine is called to write the byte values to the +stream. +

+ + + + - - + +TStream instance where the value is written. + - - + +Word value written in the routine. + - + - - - - + - - - - + - - - - + - - - - + - - - - + - - - - + - @@ -3641,11 +3467,10 @@ files are split into several strings. - + - @@ -3654,13 +3479,12 @@ files are split into several strings. - + Writes an integer value, using the smallest possible representation. - @@ -3669,101 +3493,93 @@ Writes an integer value, using the smallest possible representation. - + - - - - + - - - - + - - - - + - - - - + - - - + +Writes the specified number of Null characters to a TStream instance. + + +

+An ASCII NUL character has the value #0. +

+ - - + +TStream instance where the Null characters are written in the routine. + - - + +Number of Null characters written to the stream. If 0 is specified, a single +null character is still written to the stream. + - + - - - - + - @@ -3772,30 +3588,25 @@ Writes an integer value, using the smallest possible representation. - + - - - - - + - @@ -3810,11 +3621,10 @@ Writes an integer value, using the smallest possible representation. - + - @@ -3826,11 +3636,10 @@ Writes an integer value, using the smallest possible representation. - + - @@ -3842,11 +3651,10 @@ Writes an integer value, using the smallest possible representation. - + - @@ -3861,19 +3669,21 @@ Writes an integer value, using the smallest possible representation. - + Registers the component TLazComponentQueue. - + Raises an EReadError exception. + Raises an InvalidPropertyValue EReadError. +