From 6e22a97b9068d5e7d21f7b69fb4684688d9f4a09 Mon Sep 17 00:00:00 2001 From: juha Date: Mon, 22 Mar 2021 12:14:52 +0000 Subject: [PATCH] Docs: Updates for LCL and LazUtils. Issue #38650, patch from Don Siders. git-svn-id: trunk@64856 - --- docs/xml/lazutils/dynamicarray.xml | 37 +- docs/xml/lazutils/dynhasharray.xml | 107 ++- docs/xml/lazutils/fileutil.xml | 2 +- docs/xml/lazutils/lazfilecache.xml | 1154 +++++++++++++++-------- docs/xml/lazutils/lazmethodlist.xml | 9 +- docs/xml/lazutils/lazunicode.xml | 3 + docs/xml/lazutils/lazutf16.xml | 286 ++++-- docs/xml/lazutils/lazutf8.xml | 7 +- docs/xml/lazutils/lazutilsstrconsts.xml | 2 +- docs/xml/lazutils/lcsvutils.xml | 2 +- docs/xml/lazutils/lookupstringlist.xml | 3 + docs/xml/lazutils/maps.xml | 5 +- docs/xml/lazutils/objectlists.xml | 2 +- docs/xml/lcl/controls.xml | 70 +- 14 files changed, 1125 insertions(+), 564 deletions(-) diff --git a/docs/xml/lazutils/dynamicarray.xml b/docs/xml/lazutils/dynamicarray.xml index 1ff81e3282..a24956d27a 100644 --- a/docs/xml/lazutils/dynamicarray.xml +++ b/docs/xml/lazutils/dynamicarray.xml @@ -5,27 +5,30 @@ ==================================================================== DynamicArray ==================================================================== ---> +--> - It implements a resizable 2d array containing pointers. - + Implements a resizable 2-D array of Pointers + +

+ dynamicarray.pasimplements a resizable 2-D array of Pointers. It is used in the implementation of TCustomGrid, TDrawGrid and TStringGrid. +

+

+ This file is part of the LazUtils package. +

+

+ Author: Jesus Reyes +

+ + - - - - - - - - - - - - + + + - - + + EArray is an Exception type. Not used in the current LCL implementation. + diff --git a/docs/xml/lazutils/dynhasharray.xml b/docs/xml/lazutils/dynhasharray.xml index 7af48d6ff9..39fb23381e 100644 --- a/docs/xml/lazutils/dynhasharray.xml +++ b/docs/xml/lazutils/dynhasharray.xml @@ -7,53 +7,72 @@ ==================================================================== --> - Module of managing dynamic sets or associative arrays + Contains classes used to manage dynamic sets or associative arrays -

Extends the functionality of Pascal by offering alternative data structure : set like array (the order is not kept) with fast find/delete. Its size can change automatically during the execution of the program. The price is that it is somewhat slower than a number indexes access of an array.

-

This unit defines TDynHashArray, which is very similar to a TList, since - it also stores pointer/objects.

-

It supports Add, Remove, Contains, First, Count and Clear.

-

Because of the hashing nature the operations adding, removing and finding is - done in constant time on average.

- Inner structure: - There are three parts: - 1. The array itself (FItems). Every entry is a pointer to the first - TDynHashArrayItem of a list with the same hash index. The first item - of every same index list is the list beginning and its IsOverflow - flag is set to false. All other items are overflow items. - To get all items with the same hash index, do a FindHashItem. Then - search through all "Next" items until Next is nil or its IsOverflow - flag is set to false. - 2. The items beginning with FFirstItem is a 2-way-connected list of - TDynHashArrayItem. This list contains all used items. - 3. To reduce GetMem/FreeMem calls, free items are cached. - - Issues: - The maximum capacity is the PrimeNumber. You can store more items, but the - performance decreases. The best idea is to provide your own hash function. - - Important: Items in the TDynHashArray must not change their key. - When changing the key of an item, remove it and add it after the change. - +

+ DynHashArray.pp extends the functionality of Pascal by + offering alternative data structure: set like array (the order is not kept) + with fast find/delete. Its size can change automatically during the + execution of the program. The price is that it is somewhat slower than + a number indexes access of an array. +

+

+ This unit defines TDynHashArray, which is very similar to a TList, since + it also stores pointer/objects. +

+

+ It supports Add, Remove, Contains, First, Count and Clear. +

+

+ Because of the hashing nature the operations adding, removing and + finding is done in constant time on average. +

+

+ Inner structure: +

+

+ There are three parts: +

+
    +
  • + The array itself (FItems). Every entry is a pointer to the first + TDynHashArrayItem of a list with the same hash index. + The first item of every same index list is the list beginning + and its IsOverflow flag is set to false. All other items are + overflow items. To get all items with the same hash index, + do a FindHashItem. Then search through all "Next" items + until Next is nil or its IsOverflow flag is set to false. +
    • +
  • + The items beginning with FFirstItem is a 2-way-connected list + of TDynHashArrayItem. This list contains all used items. +
    • +
  • + To reduce GetMem/FreeMem calls, free items are cached. +
    • +
+

+ Issues: +

+

+ The maximum capacity is the PrimeNumber. You can store more items, + but the performance decreases. The best idea is to provide your own + hash function. +

+

+ Important: Items in the TDynHashArray must not change their key. When + changing the key of an item, remove it and add it after the change. +

+

+ This file is part of the LazUtils package. +

+ - - - - - - - - - - - - - - - - - + + + + Type for hash function diff --git a/docs/xml/lazutils/fileutil.xml b/docs/xml/lazutils/fileutil.xml index 9a0f962e17..581477083a 100644 --- a/docs/xml/lazutils/fileutil.xml +++ b/docs/xml/lazutils/fileutil.xml @@ -1445,7 +1445,7 @@ CopyDirTree is a Boolean function used to copy file system entries from the directory in SourceDir to the directory in TargetDir.

- Values in SourceDir and TargetDir are fully-qualified path names for the directories. TargetDir cannot be a sub-directory located in SourceDir. No actions are performed in the routine when TargetDir is located within the specified SourceDir. + Values in SourceDir and TargetDir are fully-qualified path names for the directories. If a trailing path delimiter is omitted in SourceDir or TargetDir, it is appended (when needed) to the values. TargetDir cannot be a sub-directory located in SourceDir. No actions are performed in the routine when TargetDir is located within the specified SourceDir.

Flags contains values representing the options enabled in the copy operation. The default value for the parameters is an empty set ([]) and indicates that none of the TCopyFileFlag options are enabled. The value cffCreateDestDirectory is always added to the values in Flags internally; CopyDirTree requires the destination directory to be created if it does not already exist. diff --git a/docs/xml/lazutils/lazfilecache.xml b/docs/xml/lazutils/lazfilecache.xml index 16165d1539..b91b5c444f 100644 --- a/docs/xml/lazutils/lazfilecache.xml +++ b/docs/xml/lazutils/lazfilecache.xml @@ -9,1038 +9,1356 @@ --> - + +Implements a caching mechanism for file and directory state information + +

+lazfilecache.pas implement a caching mechanism used for file and +directory state information. It is used in the implementation of the Lazarus IDE, +and in the LCL package system. +

+

+This file is part of the LazUtils package. +

 + + + + + + + - + +Represents flag values used for files or directories in the +state caching mechanism + +

+TFileStateCacheItemFlag is an enumerated type with values that +represent flags used for files or directories in the state caching mechanism. +Values from the enumeration are stored in the TFileStateCacheItemFlags +set type, and used in the implementation of the TFileStateCacheItem +class. +

 + + + - +File or directory exists - +File exists and is a directory - +File is readable - +File is writable - +File is a directory and can be searched - +File is a directory and allows new files to be created - +File is a text (not an executable binary) file - +File is an executable binary file - +file age is valid + + + +Physical file name for the file is valid - - - +Set type used to store TFileStateCacheItemFlag enumeration values + + + + - + +Contains information about a file or directory in the state caching mechanism + +

+TFileStateCacheItem is a class which contains information about a file or +directory in the state caching mechanism. TFileStateCacheItem has properties +used to represent a file or directory name (symbolic and physical), a timestamp, +and status flags. +

+

+TFileStateCacheItem is the type creates and stored in the internal AVL tree in +TFileStateCache using its FindFile method. +

 - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + - +Constructor for the class instance +

+Create is the constructor for the class instance. It sets the +initial values for the following properties: +

+
+
Filename
+
Set to the value passed in TheFilename.
+
TimeStamp
+
Set to the value passed in NewTimeStamp.
+
 - - + + - +Name for the file or directory in the cache item - +Timestamp value for the file or directory - - - - - +Gets the memory size needed to store the class instance + + + +TObject.InstanceSize - + +Number of bytes needed to store the class instance and its assigned data + - - - +Name for the file or directory in the cache item + + + + + + + +Physical name for the file or directory in the cache item + + + + - - - +Contains status flags for the cached file or directory item + + + - - - + +Contains status flags that have been tested for the cached item + + + + - +Timestamp for the cached item +

+Timestamp is an Int64 property with a timestamp value for +an item in the state caching mechanism. It is not actually a time value; it is +a counter that is assigned when the item is added to the TFileStateCache class. +It can be compared to the Timestamp value in the state cache to +determine when the item is potentially out-of-date. +

+

+Use TFileStateCache.Timestamp to determine when the cached item is +invalid. +

 + + + - +FileAge value for the file or directory +

+Age is a LongInt property with the file age for the file or +directory in the cache item. The value for the property is assigned when the +TFileStateCache.FileAgeCached method is called, and contains the value returned +from the FileAge routine in SysUtils. +

 + +FileAge - - - - - + +Specifies an event handler signalled when the timestamp for a cached item +is changed + + + - +Object instance for the event notification - +Name for the affected file or directory - + +Implements a state caching mechanism for files and directories + +

+TFileStateCache is a class which implements a state caching +mechanism for files and directories. TFileStateCache uses an internal AVL +tree to store TFileStateCacheItem instances for the items in +the state caching mechanism. The tree stores values sorted in file name +(or path) order. +

+

+The TimeStamp property contains a counter value, assigned in the +constructor, which is maintained when items are added or updated in cache +storage. The value is assigned to cached items, and provides an indication +when the cached item may be out-of-date in the cache. +

+

+TFileStateCache provides methods to add and update items in the cache, and to +access and verify state flags for the TFileStateCacheItem instances. +

 - - + + + +TAVLTree - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + - - - - - - - +Includes or excludes a value in the Flags property - - - +File or directory name for the cached item - - - +Identifies the Flag affected in the method - - - +True to include the flag, False to exclude it - +Constructor for the class instance +

+Create is the constructor for the class instance. It allocates +resources needed for the internal AVL tree used to store the file or directory +items in the cache mechanism. The address for the CompareFileStateItems +routine is used to compare and sort the items added to the AVL tree. It also +sets the initial value in the Timestamp property. +

 - - + + +TAVLTree - +Destructor for the class instance +

+Destroy is the overridden destructor for the class instance. It +frees resources allocated in and for the internal AVL tree used to store +cached file or directories. It also frees any change handler routines assigned +by calling the AddChangeTimeStampHandler method. +

+

+Destroy calls the inherited method prior to exit. +

 - - + - - - - - +Increments the lock count for the caching mechanism + + + - +Decrements the lock count for the caching mechanism +

+Raises an Exception if the lock count is 0 (or less) when the +method is called. +

 - - + + - +Indicates Lock has been called without a corresponding Unlock call +The return value is True when the internal lock count has a positive +non-zero value. - - + + - +True when the internal lock count has a positive non-zero value - + +Increments the change counter or updates an item in the state cache + +

+AFileName contains the file or directory name to update in the +storage for the cache. +

+

+When AFileName is an empty string (''), the entire cache is invalidated +by incrementing the change counter in the TimeStamp property. +If a value is provided in AFileName, a single item is invalidated in the cache +storage. The FindFile method is called to retrieve the +TFileStateCacheItem entry and to reset the values in its +TestedFlags property. +

+

+IncreaseTimeStamp signals each of the assigned change handlers for the +class instance using the value in AFileName as an argument. +

 - - + + + + + - + +Name for the file or directory invalidated in the cache, or an empty string +to invalidate all cached items + - + +Ensures that a cached item has an up-to-date "file exists" flag value + +

+FileExistsCached ensures that a cached item with the name in +AFileName has an up-to-date "file exists" flag value in the cache. +

+

+Calls Check to use the valid flag value for an existing +TFileStateCacheItem instance in the cache. If the return value from +Check is True, no additional actions are performed in the method. +

+

+Otherwise, the flag value was not present for the specified cache item. The +FileExistsUTF8 routine is called to determine if the file exists on +the local file system. SetFlag is called to update the +fsciExists flag for the cache item with the given name. +

 - - + + + - +True if the file exists on the local file system and in the cache - +Name for the file to examine in the method - + +Ensures that a cached item has an up-to-date "directory path exists" flag value + +

+DirPathExistsCached ensures that a cached item with the name in +AFileName has an up-to-date "directory path exists" flag value in +the cache. +

+

+Calls Check to use the valid flag value for an existing +TFileStateCacheItem instance in the cache. If the return value from +Check is True, no additional actions are performed in the method. +

+

+Otherwise, the flag value was not present for the specified cache item. The +DirPathExists routine is called to determine if the file exists on +the local file system. SetFlag is called to update the +fsciDirectory flag for the cache item with the given name. +

 - - + + + + - + +True if the directory exists on the local file system and in the cache + - +Name of the directory to examine in the method - + +Ensures that a cached item has an up-to-date "Directory is Writable" flag + +

+DirectoryIsWritableCached ensures that the specified directory +has an up-to-date value for its "Directory is Writable" flag in the cache. It +calls Check to use a valid flag value for an existing +TFileStateCacheItem instance in the cache. If the return value from +Check is True, no additional actions are performed in the method. +

+

+Otherwise, the flag value was not present for the specified cache item. The +DirectoryIsWritable routine is called to determine if the directory +allows new entries to be created in the path. SetFlag is called to +update the fsciDirectoryWritable flag for the cache item with the +given name. +

 - - + + + + - + +True if the specified directory is writable in the local file system +and in the cache + - +Name of the directory to examine in the method - + +Ensures that the "File is Executable" flag is up-to-date for a cache item + +

+FileIsExecutableCached ensures that the cache item for the specified +file has an up-to-date value in its "File is Executable" flag. It calls +Check to get the cache item with the given name, and to examine its +flag values. If Check returns True for the flag, no additional actions +are performed in the method. +

+

+Otherwise, the FileIsExecutable routine is called to get the return +value. SetFlag is called to apply the fsciExecutable flag +value to the cached item. +

 - - + + + + +FileIsExecutable - +True if the specified file is an executable binary - +Name for the file examined in the method - - - - - - - + +Ensures that the "File is Readable" flag is up-to-date for a cache item + + + - +True if the specified file is not read-only - +Name for the file examined in the method - - - - - - - + +Ensures that the "File is Writable" flag is up-to-date for a cache item + + + - + +True if the file is writable + - + +Name for the file examined in the method + - - - - - - - + +Ensures that the "File is Text" flag is up-to-date for a cache item + + + - +True if the file is a text file (not a binary executable) - +Name for the file examined in the method - + +Ensures that the file age is up-to-date for a cache item + +

+FileAgeCached differs from the related methods in the class instance. +It returns a LongInt value instead of a Boolean, and +contains the value from the FileAge routine in the RTL +SysUtils unit. The value represents the last date that the file +was modified, and the integer value does not include any time-related information +for the modification timestamp. +

+

+FileAgeCached cannot be used for directory names; the value is always -1 +when used for a directory name. +

+

+FileAge is not related to the TimeStamp property for the cache. +

 - - +FileAge - +File age (last modification date) for the file - +Name for the file examined in the method - +Gets (or creates) the cached item with the specified name +

+FindFile is a TFileStateCacheItem function used to get, +or optionally create, a cache entry for the file or directory in +Filename. +

+

+FindFile resolves a relative path used in Filename by calling the +ResolveDots routine. The normalized name is used to get the +TFileStateCacheItem instance in the cache used as the return value for the +method. +

+

+If Filename was not found in the cache, and CreateIfNotExists is +set to True, a TFileStateCacheItem instance is created with the +Timestamp for the cache and added to the internal storage. An +Exception is raised if the cache item could not be added +(and retrieved) using the internal AVL tree storage. +

+

+If Filename was not found in the cache, and CreateIfNotExists is set to +False, the return value is Nil. +

+

+FindFile is used to implement the Check and +IncreaseTimeStamp methods. +

 - - + + + + +TAVLTree - +Cached item with the specified name, or Nil - +Name for the file or directory to locate in the cache - +True to create a cache item if it does not already exist - + +Checks the specified cache item to get a specific flag value + +

+Check is a Boolean function used to check a flag value +in a cache item with the name in Filename. +

+

+AFlag identifies the flag value checked for the cache item. +

+

+AFile contains the cache item used to get the value for the +specified flag. The FindFile method is called to get (or create) a +cache item for the specified file or directory name. AFile is an output +parameter, and is used to return the TFileStateCacheItem instance to +the caller. +

+

+Check ensures that the cache item is valid (recent) using the +Timestamp for the class instance. When TimeStamp is more recent than +the value in the cache item, the cache item is updated with the current +Timestamp and its tested flags are cleared. +

+

+FlagIsSet is a variable parameter which contains the state for the +specific flag. True indicates the flag is set for the cache item. +False indicates that the flag was not already set in the cache item, or +has not been tested after resetting the Timestamp for an invalid cache item. +

+

+The return value is True when the flag in AFlag is one of the tested +flags in an existing cache item. It is False if the flag value has not +been accessed in the cache item, or when the Timestamp for an invalid cache +item was reset. +

+

+Check is used to implement methods which get or set specific flag values, +including: +

+
    +
  • FileExistsCached
    • +
  • DirPathExistsCached
    • +
  • DirectoryIsWritableCached
    • +
  • FileIsExecutableCached
    • +
  • FileIsReadableCached
    • +
  • FileIsWritableCached
    • +
  • FileIsTextCached
    • +
  • FileAgeCached
    • +
  • GetPhysicalFilenameCached
    • +
 - - + + + + + + + + + + + + + + - +True if the flag is has been tested and set for the cache item - +File or directory to locate in the cache - +Flag to examine for the cache item - +The cache item examined in the method - - - - - - - - - - - - +True if the flag was tested and set for the cache item - - - - - - - + +Adds the specified handler routine to the class instance + + + - +Handler routine added in the method - - - - - - - + +Removes the specified handler routine in the class instance + + + - +Handler routine removed in the method - + +Gets the memory size needed for the class instance and its data + +

+CalcMemSize is a name function used to get the amount of +memory needed for the class instance, including data stored in its properties. +The return value is a sum of the InstanceSize and the lengths for +the String values in FileName and PhysicalFilename. +

 - - + + +TObject.InstanceSize - +Memory size needed to store the class instance and its data - - - + +Timestamp (or revision) value for the cache storage + + + - + +Unit global variable with the class instance for the state caching mechanism + +

+FileStateCache is a FileStateCache variable which contains +the class instance used for the state caching mechanism. The default value for +the variable is Nil (unassigned). +

 + - - - - - - - + +Gets the File Exists flag value for the specified file name + + + - +True if the file exists on the local file system - +File name examined in the routine - - - - - - - + +Gets the Path Exists flag value for the specified directory path + + + - +True if the path exists on the local file system - +Path to the directory examined in the routine - - - - - - - + +Gets the Directory is Writable flag value for the specified path + + + - + +True if the specified directory allows files or sub-directories to be created + - +Path examined in the routine - - - - - - - + +Gets the File is Executable flag value for the specified file name + + + - + +True if the specified file is an executable (binary) file + - + +Name for the file examined in the routine + - - - - - - - + +Gets the File is Readable flag value for the specified file name + + + - + +True if the specified file is readable + - + +Name for the file examined in the routine + - - - - - - - + +Gets the File is Writable flag value for the specified file name + + + - + +True if the specified file is writable (not read-only) + - + +Name for the file examined in the routine + - - - - - - - + +Gets the File is Text flag for the specified file name + + + - + +True if the specified file is a text (not a binary executable) file + - + +Name for the file examined in the routine + - - - - - - - + +Gets the file age for the specified file or directory + + + - +File age for the specified file or directory - +File or directory name examined in the routine + + + + +Gets the physical file name for the specified file or directory name + + +

+GetPhysicalFilenameCached is a String function used to +get the physical file name for the value specified in AFileName. +The return value contains the actual file name for a symbolic link or reference +on the local file system. +

+

+EmptyOnError indicates that the return value can be an empty string +('') if AFilename cannot be resolved. When set to False, the +original file in AFileName is used as the return value. +

+

+GetPhysicalFilenameCached provides two (2) ways to resolve the value in +AFilename: +

+
    +
  • +Calling the GetPhysicalFilenameCached method in the FileStateCache +singleton (when assigned). This is the default code path in the routine. +
    • +
  • +Calling the GetPhysicalFilename routine. +
    • +
+ + + + + + + + +Actual file name for the symbolic link or reference + + +File name resolved in the routine + + +True to return an empty string if AFilename is not found - + +Invalidates one or more items in the state cache + +

+Calls the IncreaseTimeStamp method in FileStateCache +using the value in FileName as the target. When FileName exists +in the cache, it is the only item affected in the method. If FileName is an +empty string (''), all items in the cache are invalidated. +

 - - + + + + - +Name for the file or directory invalidated in the cache - - - - - - - + + + +TODO - + - + - + - - - - - - - + + + +TODO - + - + - - - - - - - - - - + - - - - - + +Integer value used as the invalid timestamp value for the cache mechanism + + + - - - - - + +Int64 value used as the invalid timestamp value for the cache mechanism + + + - - - - - - - +Increments the specified Integer timestamp value + + - +Timestamp value modified in the routine - - - - - - - +Increments the specified Int64 timestamp value + + - +Timestamp value modified in the routine - - - - - + +Specifies an event handler signalled to get the "file exists" flag for an item +in the cache + + + - +True if the file exists on the local file system - +File name examined in the event handler - - - - - + +Specifies an event handler signalled to get the file age for an item in the cache + + + - +File age for the specified file or directory - +File or directory examined in the handler - - - - - + +Event handler signalled to get the File Exists flag for the specified file name + + + - + +Event handler signalled to get the file age for the specified file name + +

+OnFileAgeCached is a TOnFileAgeCached variable with the +unit global event handler used to get the file age for a given file name. +It is signalled from the FileAgeCached routine (when assigned), and +is used instead of calling the TFileStateCache.FileAgeCached method +or the FileAgeUTF8 routine in LazUtils. +

 + + + + +FileAgeUTF8 - - + + diff --git a/docs/xml/lazutils/lazmethodlist.xml b/docs/xml/lazutils/lazmethodlist.xml index 5269d7977f..311d45f320 100644 --- a/docs/xml/lazutils/lazmethodlist.xml +++ b/docs/xml/lazutils/lazmethodlist.xml @@ -8,7 +8,14 @@ --> Implements a list of TMethod entries - + +

+ lazmethodlist.pas implements a list used TMethod instances representing event handler routines in LCL components. +

+

+ This file is part of the LazUtils package. +

+ diff --git a/docs/xml/lazutils/lazunicode.xml b/docs/xml/lazutils/lazunicode.xml index 31bc49c67a..8d7ad36beb 100644 --- a/docs/xml/lazutils/lazunicode.xml +++ b/docs/xml/lazutils/lazunicode.xml @@ -22,6 +22,9 @@ Behavior of helper functions are altered using the {$ModeSwitch UnicodeStrings} directive; the correct routines for handling UTF-8 or UTF-16 are called based on the mode switch value. +

+ This file is part of the LazUtils package. +

diff --git a/docs/xml/lazutils/lazutf16.xml b/docs/xml/lazutils/lazutf16.xml index d9a9db48a8..a8b3cffe76 100644 --- a/docs/xml/lazutils/lazutf16.xml +++ b/docs/xml/lazutils/lazutf16.xml @@ -9,152 +9,310 @@ --> - +Contains routines used for UTF-16 character and string operations +

+lazutf16.pas includes string routines which are based on UTF-16 +implementations, although it might also include routines for other encodings. +

+

+A UTF-16 based implementation for LowerCase, for example, is faster in +WideString and UnicodeString then the default UTF-8 implementation. +

+

+Currently this unit includes only UTF8LowerCaseViaTables which is based on +a UTF-16 table, but it might be extended to include various UTF-16 routines. +

+

+This file is part of the LazUtils package. +

 - +Gets the length of the UTF-16 character in the specified PWideChar value +Uses the endian-ness for the platform. Returns 0, 1, or 2. - - - - - - +Length of the UTF-16 character in the value, or 0 when Nil - - +PWideChar value examined in the routine - - - - - - - +Gets the length for the specified value in UTF-16 characters + + - - - - - - - - - - - - + + +Copies a number of UTF-16 characters at the given character position in the specified value + + + + + +UnicodeString with the values copied in the routine + + +UnicodeString with the values examined in the routine + + +1-based staring character (code point) position in the Unicode string + + +Number of characters (code points) copied in the the routine + + + + + + + + + +PWideChar value with the values examined in the routine + + +Len is the length in words of P + + +CharIndex is the position of the desired UnicodeChar (starting at 0) + + + +Pos implemented for UTF-16-encoded values + +

+UTF16Pos is a PtrInt function used to get the character +index in SearchInText where the value in SearchForText is located. StartPos +allows the search to begin at a specific character (code point). +

+

+The return value is the 1-based UTF-16 character index where the SearchForText +starts in SearchInText, or 0 when not found. +

+ + + + + +Character index where the SearchForText starts in SearchInText, or 0 when not found + + + +UTF-16-encoded value to locate in SearchInText + + +UTF-16-encoded value searched in the routine + + +Optional starting position (in UTF-16 code points, not in words) + + + +Converts ordinal values for UTF-16 code points in p to its Unicode equivalent + +

+UTF16CharacterToUnicode converts 16-bit values in p to the equivalent Unicode value. +

+

+Unpaired surrogates are invalid in any UTFs. These include any value in the range +$D800..$DBFF not followed by a value in the range $DC00..$DFFF, or any value in +the range $DC00..$DFFF not preceded by a value in the range $D800..$DBFF. +

+

+UTF16CharacterToUnicode ensures that ordinal value(s) in the reserved range(s) +are converted to the correct Unicode value. CharLen is updated to reflect whether +the values in p are a character represented by a single UTF-16 code point (1), or +requires 2 code points for the surrogate pair (2). It is set to 0 when p contains an +invalid UTF-16 code point. +

+

+The return value contains the Cardinal value for the Unicode code point, or 0 when p +contains an invalid UTF-16 code point. +

+ + + - +Unicode code point for the values in p - - +UTF-16 code points examined and converted in the routine - - +Number of UTF-16 code points for the converted character - +Converts a Unicode character value to its UTF-16 equivalent as a WideString value +

+Cardinal values below $10000 result in a single WideChar code value for the +code point. Other cardinal values result in 2 WideChar values in the result to +represent the UTF-16 code point. +

 - - - - + - - +WideString value with UTF-16 code point the Unicode character - +Unicode character value converted in the routine + + + + +

+Based on the specification defined by the Unicode consortium, at: +

+

+ +http://unicode.org/faq/utf_bom.html#utf16-7 + +

+
+Q: Are there any 16-bit values that are invalid?
+
+A: Unpaired surrogates are invalid in UTFs. These include any value in the
+range D800 to DBFF not followed by a value in the range DC00 to DFFF, or
+any value in the range DC00 to DFFF not preceded by a value in the range
+D800 to DBFF. [AF]
+
+

+Use ANextChar = #0 to indicate that there is no next char. +

+ + + + + + + + + + + + + + +Determines if the specified WideString contains valid UTF-16 code points + +

+Examines the content in AWideStr for valid UTF-16 characters. Calls +IsUTF16CharValid for consecutive code point pairs. +

+ + + + +True if the specified WideString contains valid UTF-16 code points + + +WideString examined in the routine + + + + + +

+Same as SysUtil.StringReplace but for WideStrings and UnicodeStrings, +since it's not available in FPC yet. +

+ + + + + + + + + + + + + + + + + + + + - +Converts a Unicode character value to its lowercase equivalent +

+Uses internal tables to map Unicode character ranges common to both UTF-16 and UTF-32. +

 - - - - + - - +Cardinal value for the lowercase equivalent of u - - +Unicode character vale converted to lowercase in the routine - - - - - - - + +Converts a UTF-8-encoded string to lowercase Unicode values using internal case tables + + + - - +String with the lowercase Unicode values for s - - +String with UTF-8 values converted to lowercase Unicode in the routine - - + + diff --git a/docs/xml/lazutils/lazutf8.xml b/docs/xml/lazutils/lazutf8.xml index fa9bb30b9a..437fa1c89e 100644 --- a/docs/xml/lazutils/lazutf8.xml +++ b/docs/xml/lazutils/lazutf8.xml @@ -11,7 +11,12 @@ Routines for managing UTF-8-encoded strings - lazutf8.pas contains useful routines for managing UTF-8-encoded strings. All routines are thread-safe unless explicitly stated. +

+ lazutf8.pas contains useful routines for managing UTF-8-encoded strings. All routines are thread-safe unless explicitly stated. +

+

+ This file is part of the LazUtils package. +

diff --git a/docs/xml/lazutils/lazutilsstrconsts.xml b/docs/xml/lazutils/lazutilsstrconsts.xml index 688cbc6b16..ef2b7826bc 100644 --- a/docs/xml/lazutils/lazutilsstrconsts.xml +++ b/docs/xml/lazutils/lazutilsstrconsts.xml @@ -9,7 +9,7 @@ Resource strings used in the LazUtils package - LazUtilsStrConsts contains resource strings used in the LazUtils package. The resource strings are translated using the corresponding .pot file found in the languages directory. + LazUtilsStrConsts contains resource strings used in the LazUtils package. The resource strings are translated using the corresponding .pot file found in the languages directory. diff --git a/docs/xml/lazutils/lcsvutils.xml b/docs/xml/lazutils/lcsvutils.xml index c3a4408ff6..ede9d61d93 100644 --- a/docs/xml/lazutils/lcsvutils.xml +++ b/docs/xml/lazutils/lcsvutils.xml @@ -11,7 +11,7 @@ Contains routines used to read and process Comma-separated values from a file or a stream - lcsvutils.pas contains routines used to read and process Comma-separated values from a file or a stream. It is used in the implementation of the LazUtils package and the TGrid component. + lcsvutils.pas contains routines used to read and process Comma-separated values from a file or a stream. It is used in the implementation of the LazUtils package and the TGrid component. diff --git a/docs/xml/lazutils/lookupstringlist.xml b/docs/xml/lazutils/lookupstringlist.xml index ab975038a8..60137d287b 100644 --- a/docs/xml/lazutils/lookupstringlist.xml +++ b/docs/xml/lazutils/lookupstringlist.xml @@ -11,6 +11,9 @@ Contains TLookupStringList, an unsorted StringList with a fast lookup feature +

+ lookupstringlist.pas contains TLookupStringList, an unsorted StringList with a fast lookup feature. This file is part of the LazUtils package. +

Authors: Juha Manninen / Antônio Galvão

diff --git a/docs/xml/lazutils/maps.xml b/docs/xml/lazutils/maps.xml index 78b6869fef..d92c2dbe7c 100644 --- a/docs/xml/lazutils/maps.xml +++ b/docs/xml/lazutils/maps.xml @@ -10,11 +10,14 @@ Implements a map for unique IDs to arbitrary data

- Implements a map for unique IDs to arbitrary data. The ID-to-Data mapping is stored in an Average Level Binary Tree for fast indexing. The map also maintains a linked list between the ordered items for fast iteration through its elements. The ID can be signed or unsigned, with a size of 1, 2, 4, 8, 16 or 32 bytes. The data can be of any (constant) size. + maps.pp implements a map for unique IDs to arbitrary data. The ID-to-Data mapping is stored in an Average Level Binary Tree for fast indexing. The map also maintains a linked list between the ordered items for fast iteration through its elements. The ID can be signed or unsigned, with a size of 1, 2, 4, 8, 16 or 32 bytes. The data can be of any (constant) size.

Author: Marc Weustink

+

+ This file is part of the LazUtils package. +

diff --git a/docs/xml/lazutils/objectlists.xml b/docs/xml/lazutils/objectlists.xml index f5f39cd9bc..72e34f1ed4 100644 --- a/docs/xml/lazutils/objectlists.xml +++ b/docs/xml/lazutils/objectlists.xml @@ -12,7 +12,7 @@

- Defines classes used to associate objects/pointers with objects/pointers. Converted to use generics by Juha. Item and Object types can now be defined. + objectlists.pas defines classes used to associate objects/pointers with objects/pointers. Converted to use generics by Juha. Item and Object types can now be defined.

diff --git a/docs/xml/lcl/controls.xml b/docs/xml/lcl/controls.xml index bf832e08d4..58220c2468 100644 --- a/docs/xml/lcl/controls.xml +++ b/docs/xml/lcl/controls.xml @@ -4582,11 +4582,11 @@ Another example: 

-            +-------+
+                  +-------+
             +---+ |       |
             | A | |   B   |
             +---+ |       |
-            +-------+
+                  +-------+

Centering A relative to B: @@ -5182,6 +5182,9 @@ + + Something to be ignored. For example a blank space between other objects + An object that displays an animation @@ -5203,6 +5206,9 @@ A control which allows selecting a color + + A generic column in a table + A list of choices that the user can select from @@ -5215,9 +5221,6 @@ A control which groups others, such as a TGroupBox - - Something to be ignored. For example a blank space between other objects - A graphic or picture or an icon @@ -5245,6 +5248,9 @@ A grip that the user can drag to change the size of widgets + + A generic row in a table + A control to scroll another one @@ -5254,12 +5260,21 @@ A control with tabs, like TPageControl + + Text inside of a control, like text in a row cell + A multi-line text editor (for example: TMemo, SynEdit) A single-line text editor (for example: TEdit) + + A control that holds ToolButtons + + + A button on a ToolBar + A control which allows one to drag a slider @@ -5269,6 +5284,9 @@ An item in a tree structure + + An item that doesn't fit any of the other categories + A top level window @@ -5319,20 +5337,12 @@ - - - Gets the value for the Handle property - - - Value for the property - - Gets the value for the Position property @@ -5381,7 +5391,9 @@ New value for the property + + @@ -5397,6 +5409,15 @@ Value for the property + + Gets the value for the Handle property + + + + + Value for the property + + The control that this accessible object is attached to. It might be the main accessible object of this control or it might represent a sub-part of a control @@ -5449,6 +5470,15 @@ + + Sets the value for AccessibleName + + + + + + + Setter for the property AccessibleDescription @@ -5468,6 +5498,12 @@ Creates a new child accessible object and returns it + + + + + + Inserts an already created child accessible object as a child of this one @@ -5513,6 +5549,12 @@ + + The name for this accessible object + + + + The description of this accessible object @@ -16757,7 +16799,7 @@ If you want to have the top of B the same as the top of C: Example2 For centering A relative to B: - +-------+ + +-------+ +---+ | | | A | | B | +---+ | |