@@ -19728,7 +19729,8 @@ Converts mouse coordinates to the position for a logical cell in the grid.
@@ -19746,7 +19748,8 @@ available, and used to the determine the return value.
-The default value for TabStop is True in
-TCustomGrid, and allows the control to appear in the TabOrder for a
-Parent form. When goTabs is enabled in Options, Tab and Shift+Tab cannot be
-used to exit the control.
+The default value for TabStop is True in TCustomGrid,
+and allows the control to appear in the TabOrder for a Parent form. When
+goTabs is enabled in Options, Tab and Shift+Tab cannot be used to exit the
+control.
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 -used. Cell padding is added to the calculated column width using the value in -varCellPadding. The derived column width is stored in the ColWidths property -for the column specified in ACol. +used. Cell padding is added to the calculated column width using the value +in varCellPadding. The derived column width is stored in the ColWidths +property for the column specified in ACol.
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.
-DoCompareCells is an overridden method used to compare cell values
-in the Sort method. It calls the inherited method when the OnCompareCells
-event handler has been assigned. The return value from the event handler
-contains the relative sort order for the compared cells, and uses the
-following values:
+DoCompareCells is an overridden method used to compare cell
+values in the Sort method. It calls the inherited method when the
+OnCompareCells event handler has been assigned. The return value from the
+event handler contains the relative sort order for the compared cells, and
+uses the following values:
When OnCompareCells is not assigned, the UTF8CompareLatinTextFast
-routine is called to perform the cell comparison and provide the return value
-for the method. When SortOrder is set to soDescending, the return value is
-negated.
+routine is called to perform the cell comparison and provide the return
+value for the method. When SortOrder is set to soDescending, the return
+value is negated.
-DrawColumnText is called from the DefaultDrawCell method for cells -which contain fixed column titles. +DrawColumnText is called from the DefaultDrawCell method for +cells which contain fixed column titles.
DrawTextInCell is a method used to draw the text for the cell
@@ -22973,9 +22978,9 @@ in Options.
-GetEditText is an overridden method used to get the text displayed
-in the Editor for the cell with the specified column and row numbers.
-GetEditText re-implements the method defined in the ancestor class.
+GetEditText is an overridden method used to get the text
+displayed in the Editor for the cell with the specified column and row
+numbers. GetEditText re-implements the method defined in the ancestor class.
The return value contains the string stored in Cells at the
@@ -23083,8 +23088,8 @@ character (?).
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
-handled in the method. Cells affected in the method are assigned as the
+value in TheText is used when TheHTML does not contain valid HTML that can
+be handled in the method. Cells affected in the method are assigned as the
current Selection in the grid control prior to exit.
@@ -23153,9 +23158,10 @@ coordinates.
-The value in Modified is set to False when Loaded using the
-LCL streaming mechanism. The value in Modified is changed to True when
-the Cells property is updated in the SetCells method.
+The value in Modified is set to False when Loaded using
+the LCL streaming mechanism. The value in Modified is changed to True
+when the Cells property is updated in the SetCells
+method.
Create -is the constructor for TCustomStringGrid. It
-calls the inherited Create method, and sets default styles, layout
-and alignment used in the class instance.
+calls the inherited Create method, and sets default styles,
+layout and alignment used in the class instance.
+LoadFromCSVStream is a method used to load content in the grid
+from comma-separated values stored in the specified stream.
+
+AStream is the TStream instance where the delimited values are
+stored.
+
+ADelimiter 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.
+
+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.
+
+UseTitles indicates whether the first row of values in the stream
+are treated as fixed column titles in the grid. When set to True,
+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 False, the first
+row is treated as cell data. The default value is True.
+
+FromLine 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.
+
+SkipEmptyLines indicates whether blank lines are skipped when the
+row and column values are loaded in the method. The default value is
+True, and causes any row with a single empty column value to be
+skipped.
+
+LoadFromCSVStream calls the LoadFromCSVStream routine in the
+
+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.
+
+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.
+
+Use LoadFromCSVFile to load grid content from a file containing the
+comma-separated values.
+
+Use SaveToCSVFile or SaveToCSVStream to store the content in the grid as
+comma-separated values.
+
-Creates a temporary TFileStream instance that is used to load
-values from the file in AFilename by calling the
+LoadFromCSVFile is a method used to delimited values from the file name in
+AFilename. It creates a temporary TFileStream instance
+that is used to load values from the file by calling the
LoadFromCSVStream method.
+ADelimiter 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.
+
+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.
+
+UseTitles indicates whether the first row of values are treated
+as fixed column titles in the grid. When set to True, 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 False, the first row is
+treated as cell data. The default value is True.
+
+FromLine 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.
+
+SkipEmptyLines indicates whether blank lines are skipped when the
+row and column values are loaded in the method. The default value is
+True, and causes any row with a single empty column value to be
+skipped.
+
+Use LoadFromCSVStream to load comma-separated values from a TStream instance.
+
+Use SaveToCSVFile or SaveToCSVStream to store the content in the grid as
+comma-separated values.
+
+SaveToCSVStream is a method used to save values in the grid as
+comma-separated values in the specified stream instance.
+
+AStream is the TStream instance where the grid content is written
+in the method.
+
+ADelimiter 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.
+
+WriteTitles indicates whether column titles are written at the
+beginning of the stream. When set to True, 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
+False, titles are omitted from the values output to the stream. The
+default value for the property is True.
+
+VisibleColumnsOnly 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
+True, any TGridColumn instance with its Visible property set to
+True is included in the output.
+
+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 False, and allows all columns to be
+written to the output stream.
+
+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.
+
+No actions are performed in the method if either RowCount or ColCount are
+set to 0.
+
+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.
+
+Use SaveToCSVFile to save the grid content as comma-separated values to a
+given file name.
+
+Use LoadFromCSVStream or LoadFromCSVFile to load the content in the grid
+control from comma-separated values in a stream or file.
+
+SaveToCSVFile is a method used to store the contents of the grid
+control as comma-separated values in the specified file name.
+
+AFileName contains the qualified path and file name where the CSV
+data is stored.
+
+ADelimiter 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.
+
+WriteTitles indicates whether column titles are written at the
+beginning of the file. When set to True, 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
+False, titles are omitted from the values output to the file. The
+default value for the property is True.
+
+VisibleColumnsOnly 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
+True, any TGridColumn instance with its Visible property set to
+True is included in the output.
+
+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 False, and allows all columns to be
+written to the output file.
+
+SaveToCSVFile creates a temporary TFileStream instance and calls
+SaveToCSVStream to process rows the and columns in the grid.
+
+Use SaveToCSVStream to save the grid content as comma-separated values to a
+TStream instance.
+
+Use LoadFromCSVStream or LoadFromCSVFile to load the content in the grid
+control from comma-separated values in a stream or file.
+
-Objects is an indexed TObject property which is used to
-associate an object instance with the cell specified in the ACol and ARow
+Objects is an indexed TObject property which is used
+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
-application must allocate and free the object instance, and must ensure it is
-cast to the correct type when retrieved.
+application must allocate and free the object instance, and must ensure it
+is cast to the correct type when retrieved.
While values in Cells and Objects are related, they are handled
@@ -23648,8 +23914,8 @@ assigned to Cells.
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
-freeing resources in Objects.
+remove content in the grid. The application is responsible for allocating
+and freeing resources in Objects.
Values for the Objects property are not included in the grid data read and
@@ -23750,9 +24016,10 @@ control. TStringGrid also allows a TObject instance to be stored
for each cell in the grid using the Objects property.
-TStringGrid sets the visibility for properties defined in the ancestor class.
-It has an overridden WSRegisterClass method to register properties
-(from older LCL versions) which are no longer used in LCL component streaming.
+TStringGrid sets the visibility for properties defined in the ancestor
+class. It has an overridden WSRegisterClass method to register
+properties (from older LCL versions) which are no longer used in LCL
+component streaming.
Additional information about grid usage is available on the Lazarus wiki in
@@ -23850,8 +24117,8 @@ application, then ParentColor will be automatically set to False.
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
while taking into account clDefault and ParentColor, use the
-GetColorResolvingParent method. This method might return a non-RGB color, but
-will never return clDefault. To obtain a purely RGB result use the
+GetColorResolvingParent method. This method might return a non-RGB color,
+but will never return clDefault. To obtain a purely RGB result use the
GetRGBColorResolvingParent method.
DrawBits contains a Byte value that indicates the -rectangle sides drawn in the routine. By default, all sides for the rectangle -are drawn. Use the following byte values or-ed together in +rectangle sides drawn in the routine. By default, all sides for the +rectangle are drawn. Use the following byte values or-ed together in DrawBits to specify the sides drawn:
-This is a set of zero or more choices, with some elements that enable diverse -functionality but others that are related directly with grid's look. Options -can be set at design-time or run-time. +This is a set of zero or more choices, with some elements that enable +diverse functionality but others that are related directly with grid's look. +Options can be set at design-time or run-time.
-DrawCell - The DrawCell method is virtual and may be overridden in -descendent grids to do custom drawing. The information passed to -DrawCell helps to identify which particular cell is being painted, -the physical area occupied on the screen and its visible status. See DrawCell reference for details. For each -cell the following occurs: +DrawCell - The DrawCell method is virtual and may be overridden +in descendent grids to do custom drawing. The information passed to +DrawCell helps to identify which particular cell is being +painted, the physical area occupied on the screen and its visible status. +See DrawCell reference for details. +For each cell the following occurs:
-The location of a grid's current (focused) cell (or row) can be changed using -keyboard, mouse or through code. In order to change cell focus successfully -to another position, we must test the target position to see if it is allowed -to receive cell focus. When using the keyboard, AutoAdvance -performs part of the process by finding what should be the next focused cell. -When using mouse clicks or moving by code, focus will not move from the -current cell unless the target cell is permitted to receive focus. +The location of a grid's current (focused) cell (or row) can be changed +using keyboard, mouse or through code. In order to change cell focus +successfully to another position, we must test the target position to see if +it is allowed to receive cell focus. When using the keyboard, +AutoAdvance performs part of the process by finding what should +be the next focused cell. When using mouse clicks or moving by code, focus +will not move from the current cell unless the target cell is permitted to +receive focus.
-The grid calls SelectCell to see if a cell can be focused: if this -function returns True, then the target cell identified with arguments -aCol and aRow can be focused (the current +The grid calls SelectCell to see if a cell can be focused: if +this function returns True, then the target cell identified with +arguments aCol and aRow can be focused (the current implementation of TCustomGrid simply returns True). TCustomDrawGrid and hence TDrawGrid and TStringGrid 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 this characteristics is skipped automatically in the process of finding a suitable cell. The overridden method SelectCell also calls the -user configurable event OnSelectCell: this event receives the cell -coordinates as arguments and always returns a default result of True. +user configurable event OnSelectCell: this event receives the +cell coordinates as arguments and always returns a default result of +True.
If a cell can be focused and we are sure a movement will take place, the @@ -24457,18 +24730,18 @@ values of type TColumnButtonStyle and so they are prefixed by
-cbsEllipsis - This editor style is the most generic one. A button with -ellipsis (...) appears in the editing cell and the programmer can use the -OnEditButtonClick grid event to take any programmed action when the user +cbsEllipsis - This editor style is the most generic one. A button +with ellipsis (...) appears in the editing cell and the programmer can use +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 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 @@ -24485,8 +24758,8 @@ because this event occurs in the active record, it could update the information in the active field.
cbsCheckboxColumn - This editor style is at the moment only available in TDBGrid. If a field's contents associated with the column are restricted -to a pair of values, for example, yes-no, True-false, on-off, 1-0, etc -then cbsCheckboxColumn is used to modify the appearance of a column by using -a check box representation that the user can toggle by using a mouse click or -pressing the SPACE key. +to a pair of values, for example, yes-no, True-false, on-off, 1-0, +etc. then cbsCheckboxColumn is used to modify the appearance of a column by +using a check box representation that the user can toggle by using a mouse +click or pressing the SPACE key.