paweld/lazarus
1
0
Fork 0
mirror of https://gitlab.com/freepascal.org/lazarus/lazarus.git synced 2025-06-08 02:38:17 +02:00
Code Issues Packages Projects Releases Wiki Activity

Docs: LCL/grids. Updates topic content.

Browse Source 
* Modified topics:
*  TCustomStringGrid.LoadFromCSVStream
*  TCustomStringGrid.LoadFromCSVFile
*  TCustomStringGrid.SaveToCSVStream
*  TCustomStringGrid.SaveToCSVFile
This commit is contained in:
dsiders 2022-11-11 16:31:26 +00:00
parent aa08ed2715
commit 0356249d44
1 changed files with 400 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

527
docs/xml/lcl/grids.xml
View File

@ -18631,7 +18631,8 @@ for the grid control.
<element name="TCustomGrid.OnSaveColumn"> <element name="TCustomGrid.OnSaveColumn">
<short> <short>
Event handler signalled when an entry in Columns is saved to a configuration file using the SaveContent method. Event handler signalled when an entry in Columns is saved to a configuration
file using the SaveContent method.
</short> </short>
<descr> <descr>
<p> <p>
@ -19728,7 +19729,8 @@ Converts mouse coordinates to the position for a logical cell in the grid.
<element name="TCustomGrid.MouseToGridZone"> <element name="TCustomGrid.MouseToGridZone">
<short> <short>
Converts the specified coordinates for the mouse pointer to the grid zone where they are located. Converts the specified coordinates for the mouse pointer to the grid zone
where they are located.
</short> </short>
<descr> <descr>
<p> <p>
@ -19746,7 +19748,8 @@ available, and used to the determine the return value.
<dl> <dl>
<dt>gzInvalid</dt> <dt>gzInvalid</dt>
<dd> <dd>
X and Y are located on the border or in a area not used for cells in the client area for the control. X and Y are located on the border or in a area not used for cells in the
client area for the control.
</dd> </dd>
<dt>gzFixedCells</dt> <dt>gzFixedCells</dt>
<dd> <dd>
@ -20048,10 +20051,10 @@ or Shift+Tab keys.
</short> </short>
<descr> <descr>
<p> <p>
The default value for <var>TabStop</var> is <b>True</b> in The default value for <var>TabStop</var> is <b>True</b> in <b>TCustomGrid</b>,
<b>TCustomGrid</b>, and allows the control to appear in the TabOrder for a and allows the control to appear in the TabOrder for a Parent form. When
Parent form. When goTabs is enabled in Options, Tab and Shift+Tab cannot be goTabs is enabled in Options, Tab and Shift+Tab cannot be used to exit the
used to exit the control. control.
</p> </p>
</descr> </descr>
<seealso> <seealso>
@ -22685,15 +22688,15 @@ AutoAdjustColumn visits the rows in the grid to calculate the maximum width
required for the text in each. A temporary Canvas instance is used to required for the text in each. A temporary Canvas instance is used to
calculate the width for the text. When Columns has been enabled, fonts calculate the width for the text. When Columns has been enabled, fonts
assigned to the TGridColumn instance are used. When Columns has not been assigned to the TGridColumn instance are used. When Columns has not been
enabled, TitleFont is used for fixed rows or columns. Otherwise, the Font for enabled, TitleFont is used for fixed rows or columns. Otherwise, the Font
the grid is used. for the grid is used.
</p> </p>
<p> <p>
For multi-line columns, the DrawText routine is called to calculate the text For multi-line columns, the DrawText routine is called to calculate the text
rectangle. For single-line columns, the TextExtent method in the canvas is rectangle. For single-line columns, the TextExtent method in the canvas is
used. Cell padding is added to the calculated column width using the value in used. Cell padding is added to the calculated column width using the value
varCellPadding. The derived column width is stored in the ColWidths property in varCellPadding. The derived column width is stored in the ColWidths
for the column specified in ACol. property for the column specified in ACol.
</p> </p>
<p> <p>
AutoAdjustColumn is called from the DblClick method when column auto-sizing AutoAdjustColumn is called from the DblClick method when column auto-sizing
@ -22773,11 +22776,11 @@ Performs a comparison between the specified cells in the grid control.
</short> </short>
<descr> <descr>
<p> <p>
<var>DoCompareCells</var> is an overridden method used to compare cell values <var>DoCompareCells</var> is an overridden method used to compare cell
in the Sort method. It calls the inherited method when the OnCompareCells values in the Sort method. It calls the inherited method when the
event handler has been assigned. The return value from the event handler OnCompareCells event handler has been assigned. The return value from the
contains the relative sort order for the compared cells, and uses the event handler contains the relative sort order for the compared cells, and
following values: uses the following values:
</p> </p>
<dl> <dl>
<dt>-1</dt> <dt>-1</dt>
@ -22791,9 +22794,9 @@ BRow.</dd>
</dl> </dl>
<p> <p>
When OnCompareCells is not assigned, the <var>UTF8CompareLatinTextFast</var> When OnCompareCells is not assigned, the <var>UTF8CompareLatinTextFast</var>
routine is called to perform the cell comparison and provide the return value routine is called to perform the cell comparison and provide the return
for the method. When SortOrder is set to soDescending, the return value is value for the method. When SortOrder is set to soDescending, the return
negated. value is negated.
</p> </p>
</descr> </descr>
<seealso> <seealso>
@ -22863,8 +22866,8 @@ DrawCellText methods are called to draw the sort indicator and text for the
column. column.
</p> </p>
<p> <p>
DrawColumnText is called from the <var>DefaultDrawCell</var> method for cells DrawColumnText is called from the <var>DefaultDrawCell</var> method for
which contain fixed column titles. cells which contain fixed column titles.
</p> </p>
</descr> </descr>
<seealso/> <seealso/>
@ -22883,7 +22886,9 @@ which contain fixed column titles.
</element> </element>
<element name="TCustomStringGrid.DrawTextInCell"> <element name="TCustomStringGrid.DrawTextInCell">
<short>Draws the text for the specified cell in a given drawing state.</short> <short>
Draws the text for the specified cell in a given drawing state.
</short>
<descr> <descr>
<p> <p>
<var>DrawTextInCell</var> is a method used to draw the text for the cell <var>DrawTextInCell</var> is a method used to draw the text for the cell
@ -22973,9 +22978,9 @@ in Options.
<short>Gets the text displayed in the Editor for the specified cell.</short> <short>Gets the text displayed in the Editor for the specified cell.</short>
<descr> <descr>
<p> <p>
<var>GetEditText</var> is an overridden method used to get the text displayed <var>GetEditText</var> is an overridden method used to get the text
in the Editor for the cell with the specified column and row numbers. displayed in the Editor for the cell with the specified column and row
GetEditText re-implements the method defined in the ancestor class. numbers. GetEditText re-implements the method defined in the ancestor class.
</p> </p>
<p> <p>
The return value contains the string stored in <var>Cells</var> at the The return value contains the string stored in <var>Cells</var> at the
@ -23083,8 +23088,8 @@ character (?).
</p> </p>
<p> <p>
Calls DoCellProcess to paste the values extracted from the HTML content. The Calls DoCellProcess to paste the values extracted from the HTML content. The
value in TheText is used when TheHTML does not contain valid HTML that can be value in TheText is used when TheHTML does not contain valid HTML that can
handled in the method. Cells affected in the method are assigned as the be handled in the method. Cells affected in the method are assigned as the
current Selection in the grid control prior to exit. current Selection in the grid control prior to exit.
</p> </p>
<p> <p>
@ -23153,9 +23158,10 @@ coordinates.
<short>Indicates if the content in the grid cells has been changed.</short> <short>Indicates if the content in the grid cells has been changed.</short>
<descr> <descr>
<p> <p>
The value in <var>Modified</var> is set to <b>False</b> when Loaded using the The value in <var>Modified</var> is set to <b>False</b> when Loaded using
LCL streaming mechanism. The value in Modified is changed to <b>True</b> when the LCL streaming mechanism. The value in Modified is changed to <b>True</b>
the <var>Cells</var> property is updated in the <var>SetCells</var> method. when the <var>Cells</var> property is updated in the <var>SetCells</var>
method.
</p> </p>
</descr> </descr>
<seealso> <seealso>
@ -23182,8 +23188,8 @@ DoCellProcess method when assigned.
<descr> <descr>
<p> <p>
<var>Create</var> -is the constructor for <var>TCustomStringGrid</var>. It <var>Create</var> -is the constructor for <var>TCustomStringGrid</var>. It
calls the inherited <var>Create</var> method, and sets default styles, layout calls the inherited <var>Create</var> method, and sets default styles,
and alignment used in the class instance. layout and alignment used in the class instance.
</p> </p>
</descr> </descr>
<seealso> <seealso>
@ -23411,10 +23417,88 @@ Use DeleteRow to remove a row at a specific row number in the grid.
<element name="TCustomStringGrid.LoadFromCSVStream"> <element name="TCustomStringGrid.LoadFromCSVStream">
<short> <short>
Loads the content for the grid from the delimited values in AStream. Loads the grid content from the delimited values in AStream.
</short> </short>
<descr/> <descr>
<seealso/> <p>
<var>LoadFromCSVStream</var> is a method used to load content in the grid
from comma-separated values stored in the specified stream.
</p>
<p>
<var>AStream</var> is the TStream instance where the delimited values are
stored.
</p>
<p>
<var>ADelimiter</var> is a character which identifies the delimiter used
between column values on a row. Its default value is ',' (Comma) (decimal
44), but can be changed to another character value if needed.
</p>
<p>
Each row of values is terminated by a Carriage Return (Decimal 13) or Line
Feed (Decimal 10) character. CR+LF may also be used. When LoadFromCSVStream
encounters either of the characters, it is processed as an end-of-line
marker.
</p>
<p>
<var>UseTitles</var> indicates whether the first row of values in the stream
are treated as fixed column titles in the grid. When set to <b>True</b>,
each column value is stored as the caption for the corresponding entry in
the Columns collection (when enabled). If Columns are not used, the values
are stored as cell data in row number 0. When set to <b>False</b>, the first
row is treated as cell data. The default value is <b>True</b>.
</p>
<p>
<var>FromLine</var> indicates the ordinal line number in AStream that is the
first row loaded in the method. The default value is 0, and causes stream
processing to begin at the first line. When a positive non-zero value is
used, the lines are skipped by reading the corresponding number of
end-of-line sequences from the stream.
</p>
<p>
<var>SkipEmptyLines</var> indicates whether blank lines are skipped when the
row and column values are loaded in the method. The default value is
<b>True</b>, and causes any row with a single empty column value to be
skipped.
</p>
<p>
LoadFromCSVStream calls the LoadFromCSVStream routine in the
<file>LCSVUtils</file> unit to load values from the stream. This routine
provides support for converting character encodings when needed.
</p>
<p>
LoadFromCSVStream ensures that the grid control has enough columns to
represent the values read from the stream. When Columns is enabled, its Add
method is called to create additional columns (when needed). If this occurs
on the first line and UseTitles is enabled, cell values are stored as the
Title for each of the columns. If Columns is not enabled, the value in
ColCount is updated to reflect the number of columns read from the stream.
</p>
<p>
Please note that updates to the control occur in a BeginUpdate..EndUpdate
block. This suppresses redrawing the control until all columns and rows in
the stream have been loaded.
</p>
<p>
Use LoadFromCSVFile to load grid content from a file containing the
comma-separated values.
</p>
<p>
Use SaveToCSVFile or SaveToCSVStream to store the content in the grid as
comma-separated values.
</p>
</descr>
<seealso>
<link id="TCustomStringGrid.LoadFromCSVFile"/>
<link id="TCustomStringGrid.SaveToCSVFile"/>
<link id="TCustomStringGrid.SaveToCSVStream"/>
<link id="TCustomStringGrid.Cells"/>
<link id="TCustomDrawGrid.Columns"/>
<link id="TCustomDrawGrid.ColCount"/>
<link id="TCustomDrawGrid.FixedRows"/>
<link id="TGridColumns"/>
<link id="TGridColumn.Title"/>
<link id="#lazutils.lcsvutils.LoadFromCSVStream">LoadFromCSVStream</link>
</seealso>
</element> </element>
<element name="TCustomStringGrid.LoadFromCSVStream.AStream"> <element name="TCustomStringGrid.LoadFromCSVStream.AStream">
<short>Stream with the content loaded in the method.</short> <short>Stream with the content loaded in the method.</short>
@ -23446,13 +23530,60 @@ Loads the grid from a file with delimited values for the columns and rows.
</short> </short>
<descr> <descr>
<p> <p>
Creates a temporary <var>TFileStream</var> instance that is used to load LoadFromCSVFile is a method used to delimited values from the file name in
values from the file in <var>AFilename</var> by calling the <var>AFilename</var>. It creates a temporary <var>TFileStream</var> instance
that is used to load values from the file by calling the
<var>LoadFromCSVStream</var> method. <var>LoadFromCSVStream</var> method.
</p> </p>
<p>
<var>ADelimiter</var> is a character which identifies the delimiter used
between column values on a row. Its default value is ',' (Comma) (decimal
44), but can be changed to another character value if needed.
</p>
<p>
Each row of values is terminated by a Carriage Return (Decimal 13) or Line
Feed (Decimal 10) character. CR+LF may also be used. When either of the
characters is encountered, they are processed as an end-of-line
marker.
</p>
<p>
<var>UseTitles</var> indicates whether the first row of values are treated
as fixed column titles in the grid. When set to <b>True</b>, each column
value is stored as the caption for the corresponding entry in the Columns
collection (when enabled). If Columns are not used, the values are stored as
cell data in row number 0. When set to <b>False</b>, the first row is
treated as cell data. The default value is <b>True</b>.
</p>
<p>
<var>FromLine</var> indicates the ordinal line number that is the first row
loaded in the method. The default value is 0, and causes processing to begin
at the first line. When a positive non-zero value is used, the lines are
skipped by reading the corresponding number of end-of-line sequences.
</p>
<p>
<var>SkipEmptyLines</var> indicates whether blank lines are skipped when the
row and column values are loaded in the method. The default value is
<b>True</b>, and causes any row with a single empty column value to be
skipped.
</p>
<p>
Use LoadFromCSVStream to load comma-separated values from a TStream instance.
</p>
<p>
Use SaveToCSVFile or SaveToCSVStream to store the content in the grid as
comma-separated values.
</p>
</descr> </descr>
<seealso> <seealso>
<link id="TCustomStringGrid.LoadFromCSVStream"/> <link id="TCustomStringGrid.LoadFromCSVStream"/>
<link id="TCustomStringGrid.SaveToCSVFile"/>
<link id="TCustomStringGrid.SaveToCSVStream"/>
<link id="TCustomStringGrid.Cells"/>
<link id="TCustomDrawGrid.Columns"/>
<link id="TCustomDrawGrid.ColCount"/>
<link id="TCustomDrawGrid.FixedRows"/>
<link id="TGridColumns"/>
<link id="TGridColumn.Title"/>
</seealso> </seealso>
</element> </element>
<element name="TCustomStringGrid.LoadFromCSVFile.AFilename"> <element name="TCustomStringGrid.LoadFromCSVFile.AFilename">
@ -23469,29 +23600,106 @@ Indicates if column captions are loaded from values in the file.
</short> </short>
</element> </element>
<element name="TCustomStringGrid.LoadFromCSVFile.FromLine"> <element name="TCustomStringGrid.LoadFromCSVFile.FromLine">
<short>Initial line number from the file loaded in the method.</short> <short>
Initial line number from the file loaded in the method.
</short>
</element> </element>
<element name="TCustomStringGrid.LoadFromCSVFile.SkipEmptyLines"> <element name="TCustomStringGrid.LoadFromCSVFile.SkipEmptyLines">
<short>Indicates if empty lines in the file are ignored in the method.</short> <short>
Indicates if empty lines in the file are ignored in the method.
</short>
</element> </element>
<element name="TCustomStringGrid.SaveToCSVStream"> <element name="TCustomStringGrid.SaveToCSVStream">
<short> <short>
Saves content in the grid as delimited values in the specified stream Saves grid content as comma-separated values in the specified stream
instance. instance.
</short> </short>
<descr/> <descr>
<seealso/> <p>
<var>SaveToCSVStream</var> is a method used to save values in the grid as
comma-separated values in the specified stream instance.
</p>
<p>
<var>AStream</var> is the TStream instance where the grid content is written
in the method.
</p>
<p>
<var>ADelimiter</var> is the character used as the delimiter between cell
values on each row. The default value is ',' (Comma)(Decimal 44), but can be
changed to another value if needed.
</p>
<p>
<var>WriteTitles</var> indicates whether column titles are written at the
beginning of the stream. When set to <b>True</b>, column headers are
included in the output. If the Columns collection has been enabled, the
titles are read from the TGridColumn instances in the collection. If Columns
has not been enabled, the cells in the FixedRows are written. When set to
<b>False</b>, titles are omitted from the values output to the stream. The
default value for the property is <b>True</b>.
</p>
<p>
<var>VisibleColumnsOnly</var> indicates whether the CSV output contains only
visible columns on the grid. This capability is enabled when the Columns
collection is used to defined the columns and their visibility. When set to
<b>True</b>, any TGridColumn instance with its Visible property set to
<b>True</b> is included in the output.
</p>
<p>
If Columns has not been enabled, all of the columns are by default visible
and written to the stream - regardless of the value in the argument. The
default value for the argument is <b>False</b>, and allows all columns to be
written to the output stream.
</p>
<p>
SaveToCSVStream processes values in the grid in row order. Each column
included in the output is written using the value in ADelimiter to separate
the adjacent column values. A column value is enclosed by quote characters
if its content contains whitespace or the delimiter character defined in
ADelimiter. Each row is terminated with the end-of-line sequence used in the
LCL.
</p>
<p>
No actions are performed in the method if either RowCount or ColCount are
set to 0.
</p>
<p>
Please note: the stream position in AStream is not changed after values are
written to the stream. It is positioned at the end of the stream. Use the
Seek method or the Position property in AStream to change the stream
position when needed.
</p>
<p>
Use SaveToCSVFile to save the grid content as comma-separated values to a
given file name.
</p>
<p>
Use LoadFromCSVStream or LoadFromCSVFile to load the content in the grid
control from comma-separated values in a stream or file.
</p>
</descr>
<seealso>
<link id="TCustomStringGrid.SaveToCSVFile"/>
<link id="TCustomStringGrid.Rows"/>
<link id="TCustomDrawGrid.FixedRows"/>
<link id="TCustomDrawGrid.Columns"/>
<link id="TGridColumns.Enabled"/>
<link id="TGridColumn.Title"/>
<link id="#rtl.classes.TStream">TStream</link>
</seealso>
</element> </element>
<element name="TCustomStringGrid.SaveToCSVStream.AStream"> <element name="TCustomStringGrid.SaveToCSVStream.AStream">
<short>Stream where grid content is stored.</short> <short>Stream where the grid content is stored.</short>
</element> </element>
<element name="TCustomStringGrid.SaveToCSVStream.ADelimiter"> <element name="TCustomStringGrid.SaveToCSVStream.ADelimiter">
<short>Delimiter between cell values; default is Comma (',').</short> <short>
Delimiter between cell values on the same row; default is Comma (',').
</short>
</element> </element>
<element name="TCustomStringGrid.SaveToCSVStream.WriteTitles"> <element name="TCustomStringGrid.SaveToCSVStream.WriteTitles">
<short> <short>
Indicates that column captions are stored as the first row of CSV data. Indicates that column titles are stored as the first row in the
comma-separated values. <b>False</b> omits column titles in the output.
</short> </short>
</element> </element>
<element name="TCustomStringGrid.SaveToCSVStream.VisibleColumnsOnly"> <element name="TCustomStringGrid.SaveToCSVStream.VisibleColumnsOnly">
@ -23502,10 +23710,68 @@ Indicates if only visible columns are included in the CSV output.
<element name="TCustomStringGrid.SaveToCSVFile"> <element name="TCustomStringGrid.SaveToCSVFile">
<short> <short>
Saves grid content as delimited values in the specified file name. Saves grid content as comma-separated values in the specified file name.
</short> </short>
<descr/> <descr>
<seealso/> <p>
<var>SaveToCSVFile</var> is a method used to store the contents of the grid
control as comma-separated values in the specified file name.
</p>
<p>
<var>AFileName</var> contains the qualified path and file name where the CSV
data is stored.
</p>
<p>
<var>ADelimiter</var> is the character used as the delimiter between cell
values on each row. The default value is ',' (Comma)(Decimal 44), but can be
changed to another value if needed.
</p>
<p>
<var>WriteTitles</var> indicates whether column titles are written at the
beginning of the file. When set to <b>True</b>, column headers are included
in the output. If the Columns collection has been enabled, the titles are
read from the TGridColumn instances in the collection. If Columns has not
been enabled, the cells in the FixedRows are written. When set to
<b>False</b>, titles are omitted from the values output to the file. The
default value for the property is <b>True</b>.
</p>
<p>
<var>VisibleColumnsOnly</var> indicates whether the CSV output contains only
visible columns on the grid. This capability is enabled when the Columns
collection is used to defined the columns and their visibility. When set to
<b>True</b>, any TGridColumn instance with its Visible property set to
<b>True</b> is included in the output.
</p>
<p>
If Columns has not been enabled, all of the columns are by default visible
and written to the file - regardless of the value in the argument. The
default value for the argument is <b>False</b>, and allows all columns to be
written to the output file.
</p>
<p>
SaveToCSVFile creates a temporary TFileStream instance and calls
SaveToCSVStream to process rows the and columns in the grid.
</p>
<p>
Use SaveToCSVStream to save the grid content as comma-separated values to a
TStream instance.
</p>
<p>
Use LoadFromCSVStream or LoadFromCSVFile to load the content in the grid
control from comma-separated values in a stream or file.
</p>
</descr>
<seealso>
<link id="TCustomStringGrid.SaveToCSVStream"/>
<link id="TCustomStringGrid.LoadFromCSVStream"/>
<link id="TCustomStringGrid.LoadFromCSVFile"/>
<link id="TCustomStringGrid.Rows"/>
<link id="TCustomStringGrid.Cells"/>
<link id="TCustomDrawGrid.FixedRows"/>
<link id="TCustomDrawGrid.Columns"/>
<link id="TGridColumns.Enabled"/>
<link id="TGridColumn.Title"/>
</seealso>
</element> </element>
<element name="TCustomStringGrid.SaveToCSVFile.AFileName"> <element name="TCustomStringGrid.SaveToCSVFile.AFileName">
<short>File name (with optional path) where CSV data is stored.</short> <short>File name (with optional path) where CSV data is stored.</short>
@ -23518,7 +23784,7 @@ Saves grid content as delimited values in the specified file name.
<element name="TCustomStringGrid.SaveToCSVFile.WriteTitles"> <element name="TCustomStringGrid.SaveToCSVFile.WriteTitles">
<short> <short>
Indicates if column captions are written as the first row of CSV data in the Indicates if column captions are written as the first row of CSV data in the
file. file. <b>False</b> omits column titles in the output.
</short> </short>
</element> </element>
<element name="TCustomStringGrid.SaveToCSVFile.VisibleColumnsOnly"> <element name="TCustomStringGrid.SaveToCSVFile.VisibleColumnsOnly">
@ -23635,11 +23901,11 @@ Provides indexed access to a TObject instance associated with the cell.
</short> </short>
<descr/> <descr/>
<p> <p>
<var>Objects</var> is an indexed <var>TObject</var> property which is used to <var>Objects</var> is an indexed <var>TObject</var> property which is used
associate an object instance with the cell specified in the ACol and ARow to associate an object instance with the cell specified in the ACol and ARow
index values. The property value can be any TObject descendant. The index values. The property value can be any TObject descendant. The
application must allocate and free the object instance, and must ensure it is application must allocate and free the object instance, and must ensure it
cast to the correct type when retrieved. is cast to the correct type when retrieved.
</p> </p>
<p> <p>
While values in Cells and Objects are related, they are handled While values in Cells and Objects are related, they are handled
@ -23648,8 +23914,8 @@ assigned to Cells.
</p> </p>
<p> <p>
Values stored in Objects are set to Nil when the Clean method is called to Values stored in Objects are set to Nil when the Clean method is called to
remove content in the grid. The application is responsible for allocating and remove content in the grid. The application is responsible for allocating
freeing resources in Objects. and freeing resources in Objects.
</p> </p>
<p> <p>
Values for the Objects property are not included in the grid data read and Values for the Objects property are not included in the grid data read and
@ -23750,9 +24016,10 @@ control. TStringGrid also allows a <var>TObject</var> instance to be stored
for each cell in the grid using the <var>Objects</var> property. for each cell in the grid using the <var>Objects</var> property.
</p> </p>
<p> <p>
TStringGrid sets the visibility for properties defined in the ancestor class. TStringGrid sets the visibility for properties defined in the ancestor
It has an overridden <var>WSRegisterClass</var> method to register properties class. It has an overridden <var>WSRegisterClass</var> method to register
(from older LCL versions) which are no longer used in LCL component streaming. properties (from older LCL versions) which are no longer used in LCL
component streaming.
</p> </p>
<p> <p>
Additional information about grid usage is available on the Lazarus wiki in Additional information about grid usage is available on the Lazarus wiki in
@ -23850,8 +24117,8 @@ application, then ParentColor will be automatically set to <b>False</b>.
Using ParentColor when the Color value is clDefault can cause problems in Using ParentColor when the Color value is clDefault can cause problems in
resolving the actual color value. To obtain the Color property of a control resolving the actual color value. To obtain the Color property of a control
while taking into account clDefault and ParentColor, use the while taking into account clDefault and ParentColor, use the
GetColorResolvingParent method. This method might return a non-RGB color, but GetColorResolvingParent method. This method might return a non-RGB color,
will never return clDefault. To obtain a purely RGB result use the but will never return clDefault. To obtain a purely RGB result use the
GetRGBColorResolvingParent method. GetRGBColorResolvingParent method.
</p> </p>
</descr> </descr>
@ -23963,8 +24230,8 @@ Draws a dotted rubber banding rectangle around the provided cell rectangle.
</p> </p>
<p> <p>
<var>DrawBits</var> contains a <var>Byte</var> value that indicates the <var>DrawBits</var> contains a <var>Byte</var> value that indicates the
rectangle sides drawn in the routine. By default, all sides for the rectangle rectangle sides drawn in the routine. By default, all sides for the
are drawn. Use the following byte values or-ed together in rectangle are drawn. Use the following byte values or-ed together in
<var>DrawBits</var> to specify the sides drawn: <var>DrawBits</var> to specify the sides drawn:
</p> </p>
<dl> <dl>
@ -24101,10 +24368,10 @@ widgetset theme</dd>
<tr> <tr>
<td>AltColorStartNormal</td> <td>AltColorStartNormal</td>
<td> <td>
If <b>True</b>, alternate color is always in the second row after fixed rows; If <b>True</b>, alternate color is always in the second row after fixed
the first row after fixed rows will always be the default color. If rows; the first row after fixed rows will always be the default color. If
<b>False</b>, default color is set to the first row as if there were no fixed <b>False</b>, default color is set to the first row as if there were no
rows. fixed rows.
</td> </td>
</tr> </tr>
<tr> <tr>
@ -24154,8 +24421,8 @@ Pen style used to draw lines in non fixed area, possible choices are:
<td>UseXORFeatures</td> <td>UseXORFeatures</td>
<td> <td>
If set, focus rect is drawn using XOR mode so it should make visible the If set, focus rect is drawn using XOR mode so it should make visible the
focus rect in combination with any cell color background. It also affects the focus rect in combination with any cell color background. It also affects
way that moving columns look the way that moving columns look
</td> </td>
</tr> </tr>
<tr> <tr>
@ -24190,17 +24457,17 @@ anywhere along the column's height.
<var>Options</var> <var>Options</var>
</p> </p>
<p> <p>
This is a set of zero or more choices, with some elements that enable diverse This is a set of zero or more choices, with some elements that enable
functionality but others that are related directly with grid's look. Options diverse functionality but others that are related directly with grid's look.
can be set at design-time or run-time. Options can be set at design-time or run-time.
</p> </p>
<dl> <dl>
<dt> <dt>
<var>goFixedVertLine, goFixedHorzLine</var> <var>goFixedVertLine, goFixedHorzLine</var>
</dt> </dt>
<dd> <dd>
Draws a vertical or horizontal line respectively, delimiting cells or columns Draws a vertical or horizontal line respectively, delimiting cells or
in the fixed area; active by default. columns in the fixed area; active by default.
</dd> </dd>
<dt> <dt>
<var>goVertLine, goHorzLine</var> <var>goVertLine, goHorzLine</var>
@ -24236,9 +24503,10 @@ If set, grid will do numbering of rows in first fixed column.
</dt> </dt>
<dd> <dd>
If set, the grid will try to show a different look when the mouse cursor is If set, the grid will try to show a different look when the mouse cursor is
over any fixed cell. In order for this to work, desired cell zone needs to be over any fixed cell. In order for this to work, desired cell zone needs to
enabled with the <var>HeaderHotZones</var>. Try combining this option with be enabled with the <var>HeaderHotZones</var>. Try combining this option
<var>TitleStyle</var>= <var>tsNative</var> to get themed hot tracking look. with <var>TitleStyle</var>= <var>tsNative</var> to get themed hot tracking
look.
</dd> </dd>
<dt> <dt>
<var>goHeaderPushedLook</var> <var>goHeaderPushedLook</var>
@ -24258,9 +24526,10 @@ general terms the grid is drawn by painting all rows, and each row by
painting its individual cells. The process is as follows: painting its individual cells. The process is as follows:
</p> </p>
<ul> <ul>
<li>First, the visible cells area is determined: each row is tested to see if <li>
it intersects the canvas clipping region; if it's OK, then the visible area First, the visible cells area is determined: each row is tested to see if it
is painted by drawing columns of each row. intersects the canvas clipping region; if it's OK, then the visible area is
painted by drawing columns of each row.
</li> </li>
<li> <li>
The column and row values are used to identify the cell that is about to be The column and row values are used to identify the cell that is about to be
@ -24301,12 +24570,12 @@ following elements:
</li> </li>
<li> <li>
<p> <p>
<var>DrawCell</var> - The DrawCell method is virtual and may be overridden in <var>DrawCell</var> - The DrawCell method is virtual and may be overridden
descendent grids to do custom drawing. The information passed to in descendent grids to do custom drawing. The information passed to
<var>DrawCell</var> helps to identify which particular cell is being painted, <var>DrawCell</var> helps to identify which particular cell is being
the physical area occupied on the screen and its visible status. See <link painted, the physical area occupied on the screen and its visible status.
id="TCustomGrid.DrawCell">DrawCell</link> reference for details. For each See <link id="TCustomGrid.DrawCell">DrawCell</link> reference for details.
cell the following occurs: For each cell the following occurs:
</p> </p>
<ul> <ul>
<li> <li>
@ -24314,8 +24583,9 @@ cell the following occurs:
setup with default properties for brush and font based on current visual setup with default properties for brush and font based on current visual
state. For several design and run-time properties, the text alignment is set state. For several design and run-time properties, the text alignment is set
to match programmer selection in custom columns if they exists. If to match programmer selection in custom columns if they exists. If
DefaultDrawing is <b>False</b>, brush color is set to clWindow and Font color DefaultDrawing is <b>False</b>, brush color is set to clWindow and Font
to clWindowText, the text alignment is set to the DefaultTextStyle value. color to clWindowText, the text alignment is set to the DefaultTextStyle
value.
</li> </li>
<li> <li>
<b>OnPrepareCanvas</b> - If the programmer wrote an event handler for the <b>OnPrepareCanvas</b> - If the programmer wrote an event handler for the
@ -24326,34 +24596,35 @@ different combinations of left, center, top, bottom, right alignment, etc.
Any change made to the canvas for a particular cell in this event would be Any change made to the canvas for a particular cell in this event would be
lost, because the next cell drawing will reset canvas again to a default lost, because the next cell drawing will reset canvas again to a default
state. So it's safe doing changes only for a particular cell or cells and state. So it's safe doing changes only for a particular cell or cells and
forget about it for the rest. Using this event sometimes helps to avoid using forget about it for the rest. Using this event sometimes helps to avoid
the <var>OnDrawCell</var> grid event, where users would be forced to using the <var>OnDrawCell</var> grid event, where users would be forced to
duplicate the grid's drawing code. duplicate the grid's drawing code.
</li> </li>
<li> <li>
<b>OnDrawCell</b> - Next, if no handler for the <var>OnDrawCell</var> event <b>OnDrawCell</b> - Next, if no handler for the <var>OnDrawCell</var> event
was specified, the grid calls the <var>DefaultDrawCell</var> method which was specified, the grid calls the <var>DefaultDrawCell</var> method which
simply paints the cell background using the current canvas brush color and simply paints the cell background using the current canvas brush color and
style. If the <var>OnDrawCell</var> handler exists, the grid first paints the style. If the <var>OnDrawCell</var> handler exists, the grid first paints
cell background, but only if the <var>DefaultDrawing</var> was set; then it the cell background, but only if the <var>DefaultDrawing</var> was set; then
calls the <var>OnDrawCell</var> event to do custom cell painting. Usually it calls the <var>OnDrawCell</var> event to do custom cell painting. Usually
programmers want to do custom drawing only for particular cells, but standard programmers want to do custom drawing only for particular cells, but
drawing for others: in this case, they can restrict custom operation to standard drawing for others: in this case, they can restrict custom
certain cell or cells by looking into <var>ACol, ARow</var> and operation to certain cell or cells by looking into <var>ACol, ARow</var> and
<var>AState</var> arguments, and for other cells simply call the <var>AState</var> arguments, and for other cells simply call the
<var>DefaultDrawCell</var> method and let the grid to take care of it. <var>DefaultDrawCell</var> method and let the grid to take care of it.
</li> </li>
<li> <li>
<b>Text</b> - At this point, if the <var>DefaultDrawing</var> is <b>True</b>, <b>Text</b> - At this point, if the <var>DefaultDrawing</var> is
the cell's text content is painted (only for <var>TStringGrid</var>). <b>True</b>, the cell's text content is painted (only for
<var>TStringGrid</var>).
</li> </li>
<li> <li>
<b>Grid lines</b> - The last step for each cell is to paint the grid lines: <b>Grid lines</b> - The last step for each cell is to paint the grid lines:
if grid options <var>goVertLine, goHorzLine, goFixedVertLine</var> and if grid options <var>goVertLine, goHorzLine, goFixedVertLine</var> and
<var>goFixedHorzLine</var> are specified the cell grid is drawn at this <var>goFixedHorzLine</var> are specified the cell grid is drawn at this
point. Grids with only rows or only cols can be obtained by changing these point. Grids with only rows or only cols can be obtained by changing these
options. If the programmer elected to have a "themed" look it is done at this options. If the programmer elected to have a "themed" look it is done at
point also (see TitleStyle). this point also (see TitleStyle).
</li> </li>
<li> <li>
<b>FocusRect</b> - When all columns of the current row have been painted it <b>FocusRect</b> - When all columns of the current row have been painted it
@ -24367,26 +24638,28 @@ whole row if the <var>goRowSelect</var> option is set.
<b>Grid Cell Selection</b> <b>Grid Cell Selection</b>
</p> </p>
<p> <p>
The location of a grid's current (focused) cell (or row) can be changed using The location of a grid's current (focused) cell (or row) can be changed
keyboard, mouse or through code. In order to change cell focus successfully using keyboard, mouse or through code. In order to change cell focus
to another position, we must test the target position to see if it is allowed successfully to another position, we must test the target position to see if
to receive cell focus. When using the keyboard, <var>AutoAdvance</var> it is allowed to receive cell focus. When using the keyboard,
performs part of the process by finding what should be the next focused cell. <var>AutoAdvance</var> performs part of the process by finding what should
When using mouse clicks or moving by code, focus will not move from the be the next focused cell. When using mouse clicks or moving by code, focus
current cell unless the target cell is permitted to receive focus. will not move from the current cell unless the target cell is permitted to
receive focus.
</p> </p>
<p> <p>
The grid calls <var>SelectCell</var> to see if a cell can be focused: if this The grid calls <var>SelectCell</var> to see if a cell can be focused: if
function returns <b>True</b>, then the target cell identified with arguments this function returns <b>True</b>, then the target cell identified with
<var>aCol</var> and <var>aRow</var> can be focused (the current arguments <var>aCol</var> and <var>aRow</var> can be focused (the current
implementation of <var>TCustomGrid</var> simply returns <b>True</b>). implementation of <var>TCustomGrid</var> simply returns <b>True</b>).
<var>TCustomDrawGrid</var> and hence <var>TDrawGrid</var> and <var>TCustomDrawGrid</var> and hence <var>TDrawGrid</var> and
<var>TStringGrid</var> override this method and check first if a cell is any <var>TStringGrid</var> override this method and check first if a cell is any
wider than 0; normally you don't want a 0 width cell selected so a cell with wider than 0; normally you don't want a 0 width cell selected so a cell with
this characteristics is skipped automatically in the process of finding a this characteristics is skipped automatically in the process of finding a
suitable cell. The overridden method <var>SelectCell</var> also calls the suitable cell. The overridden method <var>SelectCell</var> also calls the
user configurable event <var>OnSelectCell</var>: this event receives the cell user configurable event <var>OnSelectCell</var>: this event receives the
coordinates as arguments and always returns a default result of <b>True</b>. cell coordinates as arguments and always returns a default result of
<b>True</b>.
</p> </p>
<p> <p>
If a cell can be focused and we are sure a movement will take place, the If a cell can be focused and we are sure a movement will take place, the
@ -24457,18 +24730,18 @@ values of type <var>TColumnButtonStyle</var> and so they are prefixed by
<li> <li>
<b>cbsAuto</b> - This is the default editor style for TCustomGrid derived <b>cbsAuto</b> - This is the default editor style for TCustomGrid derived
grids. The TStringCellEditor derived from TCustomMaskEdit is specialized to grids. The TStringCellEditor derived from TCustomMaskEdit is specialized to
edit single line strings and is used by default in TStringGrid and TDrawGrid. edit single line strings and is used by default in TStringGrid and
When using Custom Columns, if the programmer filled the Column's PickList TDrawGrid. When using Custom Columns, if the programmer filled the Column's
property, this behaves as if cbsPickList editor style was set. For a PickList property, this behaves as if cbsPickList editor style was set. For
TCustomDBGrid that has a field of type Boolean, it behaves as if a TCustomDBGrid that has a field of type Boolean, it behaves as if
cbsCheckBoxColumn editor style was specified. This is the recommended value cbsCheckBoxColumn editor style was specified. This is the recommended value
for custom cell editors. for custom cell editors.
</li> </li>
<li> <li>
<p> <p>
<b>cbsEllipsis</b> - This editor style is the most generic one. A button with <b>cbsEllipsis</b> - This editor style is the most generic one. A button
ellipsis (...) appears in the editing cell and the programmer can use the with ellipsis (...) appears in the editing cell and the programmer can use
OnEditButtonClick grid event to take any programmed action when the user the OnEditButtonClick grid event to take any programmed action when the user
presses the button. For example a calendar dialog could pop up to allow the presses the button. For example a calendar dialog could pop up to allow the
user to select a specific date, a file open dialog could appear to find user to select a specific date, a file open dialog could appear to find
files, or a calculator could appear so the user could enter the numeric files, or a calculator could appear so the user could enter the numeric
@ -24485,8 +24758,8 @@ because this event occurs in the active record, it could update the
information in the active field. information in the active field.
</li> </li>
<li> <li>
This editor style is implemented using TButtonCellEditor, a direct descendant This editor style is implemented using TButtonCellEditor, a direct
of TButton. descendant of TButton.
</li> </li>
</ul> </ul>
</li> </li>
@ -24511,10 +24784,10 @@ PickList property for the column.
<p> <p>
<b>cbsCheckboxColumn</b> - This editor style is at the moment only available <b>cbsCheckboxColumn</b> - This editor style is at the moment only available
in TDBGrid. If a field's contents associated with the column are restricted in TDBGrid. If a field's contents associated with the column are restricted
to a pair of values, for example, yes-no, <b>True</b>-false, on-off, 1-0, etc to a pair of values, for example, yes-no, <b>True</b>-false, on-off, 1-0,
then cbsCheckboxColumn is used to modify the appearance of a column by using etc. then cbsCheckboxColumn is used to modify the appearance of a column by
a check box representation that the user can toggle by using a mouse click or using a check box representation that the user can toggle by using a mouse
pressing the SPACE key. click or pressing the SPACE key.
</p> </p>
<ul> <ul>
<li> <li>
@ -24525,8 +24798,8 @@ enabled using DBGrid's OptionsExtra property; setting dgeCheckboxColumn
element to <b>False</b> disables this feature. element to <b>False</b> disables this feature.
</li> </li>
<li> <li>
The values that are used to recognize the checked or unchecked states are set The values that are used to recognize the checked or unchecked states are
in a column's properties ValueChecked and ValueUnchecked. set in a column's properties ValueChecked and ValueUnchecked.
</li> </li>
<li> <li>
At any moment, the field value can be in one of three states: Unchecked, At any moment, the field value can be in one of three states: Unchecked,