mirror of
https://gitlab.com/freepascal.org/lazarus/lazarus.git
synced 2025-04-05 22:38:03 +02:00
523 lines
14 KiB
XML
523 lines
14 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!--
|
|
|
|
Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus
|
|
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0
|
|
International public license.
|
|
|
|
https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
|
|
https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/docs/cc-by-sa-4-0.txt
|
|
|
|
Copyright (c) 1997-2025, by the Lazarus Development Team.
|
|
|
|
-->
|
|
<fpdoc-descriptions>
|
|
<package name="lazutils">
|
|
<!--
|
|
====================================================================
|
|
LazUtilities
|
|
====================================================================
|
|
-->
|
|
<module name="LazUtilities">
|
|
<short>
|
|
Contains miscellaneous utility routines and variables used in the Lazarus IDE
|
|
and LCL.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<file>lazutilities.pas</file> is part of the <file>LazUtils</file> package.
|
|
</p>
|
|
</descr>
|
|
|
|
<!-- unresolved external references -->
|
|
<element name="Classes"/>
|
|
<element name="SysUtils"/>
|
|
<element name="TypInfo"/>
|
|
|
|
<element name="TGetSkipCheckByKey">
|
|
<short>
|
|
Specifies a Boolean function type used to implement the GetSkipCheckByKey and
|
|
SetSkipCheckByKeyProc routines.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
The function type includes the <var>AKey</var> string argument which contains
|
|
the key value to locate in the function. TGetSkipCheckByKey is used in the
|
|
Lazarus IDE to implement a routine which checks command line parameters for a
|
|
language identifier.
|
|
</p>
|
|
</descr>
|
|
<version>
|
|
Added in LazUtils version 3.0.
|
|
</version>
|
|
<seealso>
|
|
<link id="GetSkipCheckByKey"/>
|
|
<link id="SetSkipCheckByKeyProc"/>
|
|
</seealso>
|
|
</element>
|
|
|
|
<element name="TStringsSortCompare">
|
|
<short>
|
|
Specifies a comparison function type for string values in a TStrings instance.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
TStringsSortCompare is an Integer function type used to compare string values
|
|
to determine the relative sort order. The return value indicates the relative
|
|
sort order for the compared items, and normally contains a value like the one
|
|
returned from CompareText. For example:
|
|
</p>
|
|
<dl>
|
|
<dt><0</dt>
|
|
<dd>Item1 has a value that comes before Item2.</dd>
|
|
<dt>0</dt>
|
|
<dd>Item1 and Item2 have the same value.</dd>
|
|
<dt>>0</dt>
|
|
<dd>Item1 has a value that comes after Item2.</dd>
|
|
</dl>
|
|
<p>
|
|
The address for a TStringsSortCompare type is passed as an argument to the
|
|
MergeSort routine.
|
|
</p>
|
|
</descr>
|
|
<version>
|
|
Added in LazUtils version 4.0. Replaces the TStringsSortCompare type in the
|
|
<file>lclproc.pas</file> unit (<b>LCL</b>).
|
|
</version>
|
|
<seealso>
|
|
<link id="MergeSort"/>
|
|
</seealso>
|
|
</element>
|
|
<element name="TStringsSortCompare.Result">
|
|
<short>Integer with the relative sort order for the compared values.</short>
|
|
</element>
|
|
<element name="TStringsSortCompare.Item1">
|
|
<short>First string value for the comparison.</short>
|
|
</element>
|
|
<element name="TStringsSortCompare.Item2">
|
|
<short>Second string value for the comparison.</short>
|
|
</element>
|
|
|
|
<element name="GetSkipCheckByKey">
|
|
<short>
|
|
Gets and executes the function assigned to an implementation variable using
|
|
the specified argument.
|
|
</short>
|
|
<descr/>
|
|
<version>
|
|
Added in LazUtils version 3.0.
|
|
</version>
|
|
<seealso/>
|
|
</element>
|
|
<element name="GetSkipCheckByKey.Result">
|
|
<short>
|
|
<b>True</b> if a function was assigned to the implementation variable,
|
|
executed in the routine, and returned <b>True</b>. Otherwise, <b>False</b>.
|
|
</short>
|
|
</element>
|
|
<element name="GetSkipCheckByKey.AKey">
|
|
<short>
|
|
Value
|
|
</short>
|
|
</element>
|
|
|
|
<element name="SetSkipCheckByKeyProc">
|
|
<short>
|
|
Sets the value for an implementation variable to the specified function.
|
|
</short>
|
|
<descr/>
|
|
<version>
|
|
Added in LazUtils version 3.0.
|
|
</version>
|
|
<seealso/>
|
|
</element>
|
|
<element name="SetSkipCheckByKeyProc.AProc">
|
|
<short>
|
|
Function type assigned to the implementation variable.
|
|
</short>
|
|
</element>
|
|
|
|
<element name="FreeThenNil">
|
|
<short>
|
|
Ensures that the specified object instance is freed and set to Nil.
|
|
</short>
|
|
<descr>
|
|
<var>FreeThenNil</var> is a procedure used to ensure that the object instance
|
|
in <var>obj</var> is freed and set to Nil. If obj has been assigned, it is
|
|
cast to a <var>TObject</var> instance and its Free method is called. Finally,
|
|
the pointer to the address in obj is set to Nil.
|
|
</descr>
|
|
<seealso/>
|
|
</element>
|
|
<element name="FreeThenNil.obj">
|
|
<short>Object instance modified in the routine.</short>
|
|
</element>
|
|
|
|
<element name="ComparePointers">
|
|
<short>Gets the relative order for the specified Pointers.</short>
|
|
<descr>
|
|
<p>
|
|
<var>ComparePointers</var> is an <var>Integer</var> function used to get the
|
|
relative order for the specified Pointer values. The following return values
|
|
are used in the routine:
|
|
</p>
|
|
<dl>
|
|
<dt>1</dt>
|
|
<dd>Returned when p1 > p2.</dd>
|
|
<dt>0</dt>
|
|
<dd>Returned when p1 = p2.</dd>
|
|
<dt>-1</dt>
|
|
<dd>Returned when p1 < p2.</dd>
|
|
</dl>
|
|
</descr>
|
|
<seealso/>
|
|
</element>
|
|
<element name="ComparePointers.Result">
|
|
<short>
|
|
Numeric value with the relative order for the compared Pointers.
|
|
</short>
|
|
</element>
|
|
<element name="ComparePointers.p1">
|
|
<short>Pointer compared in the routine.</short>
|
|
</element>
|
|
<element name="ComparePointers.p2">
|
|
<short>Pointer compared in the routine.</short>
|
|
</element>
|
|
|
|
<element name="CompareBoolean">
|
|
<short>Compares the specified Boolean values.</short>
|
|
<descr>
|
|
<dl>
|
|
<dt>0</dt>
|
|
<dd>Returned when b1 and b2 have the same value.</dd>
|
|
<dt>1</dt>
|
|
<dd>Returned when b1 is <b>True</b>.</dd>
|
|
<dt>-1</dt>
|
|
<dd>Returned as the default value (when b1 is <b>False</b>).</dd>
|
|
</dl>
|
|
</descr>
|
|
<seealso/>
|
|
</element>
|
|
<element name="CompareBoolean.Result">
|
|
<short>Numeric value for the comparison.</short>
|
|
</element>
|
|
<element name="CompareBoolean.b1">
|
|
<short>Boolean value compared in the routine.</short>
|
|
</element>
|
|
<element name="CompareBoolean.b2">
|
|
<short>Boolean value compared in the routine.</short>
|
|
</element>
|
|
|
|
<element name="GetEnumValueDef">
|
|
<short>
|
|
Gets the ordinal position for an enumeration value with the specified name.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>GetEnumValueDef</var> is an <var>Integer</var> function used to get the
|
|
ordinal position in the specified enumeration type insformation for the value
|
|
with the given name.
|
|
</p>
|
|
<p>
|
|
The return value contains the ordinal position in <var>TypeInfo</var> for the
|
|
enumeration value with the given <var>Name</var>. GetEnumValueDef calls
|
|
<var>GetEnumValue</var> to find the value in Name in the type information. If
|
|
the return value is <b>-1</b>, an enumeration value with the specified name
|
|
is not found in TypeInfo and the value in <var>DefaultValue</var> is used as
|
|
the return value.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="#rtl.typinfo.GetEnumValue">GetEnumValue</link>
|
|
<link id="#rtl.typinfo.PTypeInfo">PTypeInfo</link>
|
|
</seealso>
|
|
</element>
|
|
<element name="GetEnumValueDef.Result">
|
|
<short>
|
|
Ordinal position for the enumeration value with the specified name.
|
|
</short>
|
|
</element>
|
|
<element name="GetEnumValueDef.TypeInfo">
|
|
<short>Pointer to the type information examined in the routine.</short>
|
|
</element>
|
|
<element name="GetEnumValueDef.Name">
|
|
<short>Name for the enumeration value to locate in TypeInfo.</short>
|
|
</element>
|
|
<element name="GetEnumValueDef.DefaultValue">
|
|
<short>
|
|
Default ordinal position for the enumeration value used when Name is not
|
|
found.
|
|
</short>
|
|
</element>
|
|
|
|
<element name="RoundToInt">
|
|
<short>Rounds the specified Extended value to an Integer value.</short>
|
|
<descr>
|
|
<p>
|
|
Calls <var>Round</var> to round the <var>Extended</var> value, and casts the
|
|
result to the <var>Integer</var> type used as the return value.
|
|
</p>
|
|
</descr>
|
|
<seealso/>
|
|
</element>
|
|
<element name="RoundToInt.Result">
|
|
<short>Integer value for the rounded numeric value.</short>
|
|
</element>
|
|
<element name="RoundToInt.e">
|
|
<short>Extended type rounded and converted in the routine.</short>
|
|
</element>
|
|
|
|
<element name="RoundToCardinal">
|
|
<short>Rounds the specified Extended value to a Cardinal value.</short>
|
|
<descr>
|
|
<p>
|
|
Calls <var>Round</var> to round the <var>Extended</var> value, and casts the
|
|
result to the <var>Cardinal</var> type used as the return value.
|
|
</p>
|
|
</descr>
|
|
<seealso/>
|
|
</element>
|
|
<element name="RoundToCardinal.Result">
|
|
<short>Cardinal value for the rounded numeric value.</short>
|
|
</element>
|
|
<element name="RoundToCardinal.e">
|
|
<short>Extended type rounded and converted in the routine.</short>
|
|
</element>
|
|
|
|
<element name="TruncToInt">
|
|
<short>Truncates the extended value and returns an Integer type.</short>
|
|
<descr/>
|
|
<seealso/>
|
|
</element>
|
|
<element name="TruncToInt.Result">
|
|
<short>Integer type with the truncated value.</short>
|
|
</element>
|
|
<element name="TruncToInt.e">
|
|
<short>Extended value truncated and converted in the routine.</short>
|
|
</element>
|
|
|
|
<element name="TruncToCardinal">
|
|
<short>Truncates the extended value and returns a Cardinal type.</short>
|
|
<descr/>
|
|
<seealso/>
|
|
</element>
|
|
<element name="TruncToCardinal.Result">
|
|
<short>Cardinal type with the truncated value.</short>
|
|
</element>
|
|
<element name="TruncToCardinal.e">
|
|
<short>Extended value truncated and converted in the routine.</short>
|
|
</element>
|
|
|
|
<element name="StrToDouble">
|
|
<short>Converts the specified string value to a Double type.</short>
|
|
<descr>
|
|
<p>
|
|
Calls <var>StrToFloat</var> to convert the value in <var>s</var>, and casts
|
|
the result to the <var>Double</var> data type used as the return value.
|
|
</p>
|
|
</descr>
|
|
<seealso/>
|
|
</element>
|
|
<element name="StrToDouble.Result">
|
|
<short>Double type with the converted value.</short>
|
|
</element>
|
|
<element name="StrToDouble.s">
|
|
<short>String value converted in the routine.</short>
|
|
</element>
|
|
|
|
<element name="CreateFirstIdentifier">
|
|
<short>
|
|
Gets the name for the first identifier represented by the value specified in
|
|
Identifier.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>CreateFirstIdentifier</var> removes any numeric characters found at the
|
|
end of <var>Identifier</var>, and replaces them with the value '1'.
|
|
</p>
|
|
<p>
|
|
For example:
|
|
</p>
|
|
<code>
|
|
AIdent := CreateFirstIdentifier('Edit9');
|
|
// AIdent = 'Edit1'
|
|
</code>
|
|
<p>
|
|
CreateFirstIdentifier is used to implement code macros, key mappings, and menu
|
|
items in the Lazarus IDE.
|
|
</p>
|
|
<p>
|
|
Use CreateNextIdentifier to get the next name for a specified identifier value.
|
|
</p>
|
|
</descr>
|
|
<version>
|
|
Added in LazUtils version 4.0. Replaces the CreateFirstIdentifier routine in
|
|
the <file>lclproc.pas</file> unit (<b>LCL</b>).
|
|
</version>
|
|
<seealso>
|
|
<link id="CreateNextIdentifier"/>
|
|
</seealso>
|
|
</element>
|
|
<element name="CreateFirstIdentifier.Result">
|
|
<short>
|
|
First identifier name for the value specified in Identifier.
|
|
</short>
|
|
</element>
|
|
<element name="CreateFirstIdentifier.Identifier">
|
|
<short>
|
|
Name for an identifier used as the base name in the generated value.
|
|
</short>
|
|
</element>
|
|
|
|
<element name="CreateNextIdentifier">
|
|
<short>
|
|
Gets the name for the next identifier following the value specified in
|
|
Identifier.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>CreateNextIdentifier</var> examines the value in <var>Identifier</var> to
|
|
get the numeric characters in the suffix for the identifier name. It converts
|
|
the digits to an Integer and increments the value. The value is converted to a
|
|
String and appended as the numeric suffix for the base identifier name.
|
|
</p>
|
|
<p>
|
|
For example:
|
|
</p>
|
|
<code>
|
|
AIdent := CreateNextIdentifier('Edit19');
|
|
// AIdent = 'Edit20'
|
|
</code>
|
|
<p>
|
|
CreateNextIdentifier is used to implement commands, menu items, component
|
|
editors, and design-time layouts in the Lazarus IDE.
|
|
</p>
|
|
<p>
|
|
Use CreateFirstIdentifier to get the first identifier name for a specified
|
|
value.
|
|
</p>
|
|
</descr>
|
|
<version>
|
|
Added in LazUtils version 4.0. Replaces the CreateNextIdentifier routine in the
|
|
<file>lclproc.pas</file> unit (<b>LCL</b>).
|
|
</version>
|
|
<seealso>
|
|
<link id="CreateFirstIdentifier"/>
|
|
</seealso>
|
|
</element>
|
|
<element name="CreateNextIdentifier.Result">
|
|
Next identifier name for the value specified in Identifier.
|
|
</element>
|
|
<element name="CreateNextIdentifier.Identifier">
|
|
<short>
|
|
Name for an identifier with the base name and numeric suffix used to generate
|
|
the return value.
|
|
</short>
|
|
</element>
|
|
|
|
<element name="MergeSort">
|
|
<short>Implements a merge/sort for TStrings or TFPList.</short>
|
|
<descr>
|
|
<p>
|
|
MergeSort is an overloaded routine used to implement a comparison-based sort
|
|
routine for values in List. List can be a TStrings or TFPList instance. No
|
|
actions are performed in the routine when List has not been assigned
|
|
(contains <b>Nil</b>).
|
|
</p>
|
|
<p>
|
|
The StartIndex and EndIndex arguments allow the initial and final entries in
|
|
a TFPList instance to be specified. When the values are omitted, they default
|
|
to the first value (position 0) and the last value (Count-1) in List.
|
|
</p>
|
|
<p>
|
|
OnCompare is the comparison routine used to determine the order for the
|
|
sorted values. It can be a TListSortCompare or TStringsSortCompare function,
|
|
depending on the overloaded variant of the called routine.
|
|
</p>
|
|
<p>
|
|
MergeSort implements the J. von Nuemann divide-and-conquer algorithm, with an
|
|
insertion sort used for lists with 6 or fewer elements.
|
|
</p>
|
|
</descr>
|
|
<version>
|
|
Added in LazUtils version 4.0. Replaces the MergeSort routine in the
|
|
<file>lclproc.pas</file> unit (<b>LCL</b>).
|
|
</version>
|
|
<seealso>
|
|
<link id="TStringsSortCompare"/>
|
|
<link id="#rtl.classes.TListSortCompare">TListSortCompare</link>
|
|
</seealso>
|
|
<seealso/>
|
|
</element>
|
|
<element name="MergeSort.List">
|
|
<short>
|
|
The list of values to sort (overloaded type).
|
|
</short>
|
|
</element>
|
|
<element name="MergeSort.OnCompare">
|
|
<short>
|
|
The sort compare function used to compare items in the list.
|
|
</short>
|
|
</element>
|
|
<element name="MergeSort.StartIndex">
|
|
<short>
|
|
The initial entry in List used in the merge/sort.
|
|
</short>
|
|
</element>
|
|
<element name="MergeSort.EndIndex">
|
|
<short>
|
|
The final entry in List used in the merge/sort.
|
|
</short>
|
|
</element>
|
|
|
|
<element name="MergeSortWithLen">
|
|
<short>
|
|
Implements a merge/sort algorithm for a list of pointers with the given
|
|
length.
|
|
</short>
|
|
<descr/>
|
|
<seealso/>
|
|
</element>
|
|
<element name="MergeSortWithLen.List">
|
|
<short>
|
|
PPointer to the list of items examined in the merge/sort routine.
|
|
</short>
|
|
</element>
|
|
<element name="MergeSortWithLen.ListLength">
|
|
<short>
|
|
PtrInt with the length for the List argument.
|
|
</short>
|
|
</element>
|
|
<element name="MergeSortWithLen.Compare">
|
|
<short>
|
|
TListSortCompare routine used to compare items for the merge/sort algorithm.
|
|
</short>
|
|
</element>
|
|
|
|
<element name="ConsoleVerbosity">
|
|
<short>Level of detail displayed in IDE console output windows.</short>
|
|
<descr>
|
|
<p>
|
|
<var>ConsoleVerbosity</var> is an Integer variable which indicates the level
|
|
of detail output from tools like pas2js and CodeTools. ConsoleVerbosity
|
|
enables debugger output for specific levels of detail.
|
|
</p>
|
|
<dl>
|
|
<dt>-1</dt>
|
|
<dd>Quiet</dd>
|
|
<dt>0</dt>
|
|
<dd>Normal verbosity (No debugger output)</dd>
|
|
<dt>1</dt>
|
|
<dd>Verbose (Debugger output enabled)</dd>
|
|
<dt>2</dt>
|
|
<dd>Very verbose (Debugger output enabled)</dd>
|
|
</dl>
|
|
</descr>
|
|
<seealso/>
|
|
</element>
|
|
|
|
</module>
|
|
<!-- LazUtilities -->
|
|
</package>
|
|
</fpdoc-descriptions>
|