From 218438a9bc7e4f3defffeb6370a457f6fb935325 Mon Sep 17 00:00:00 2001 From: dsiders Date: Sun, 16 Oct 2022 03:12:15 +0100 Subject: [PATCH] Docs: LCL/grids. Adds, updates content in TCustomGrid topics. --- docs/xml/lcl/grids.xml | 383 ++++++++++++++++++++++++++++++++++------- 1 file changed, 320 insertions(+), 63 deletions(-) diff --git a/docs/xml/lcl/grids.xml b/docs/xml/lcl/grids.xml index 42c9c17f77..ce05241f66 100644 --- a/docs/xml/lcl/grids.xml +++ b/docs/xml/lcl/grids.xml @@ -15641,14 +15641,19 @@ valid column index for the grid control.

MoveExtend is called to move the selection to the cell at the coordinates in Row and Col. The cell editor is also retrieved (when available) and is -displayed. -

-

-MoveExtend is called to move the selection to the cell at the coordinates in -Row and Col. The cell editor is also retrieved (when available) and is -displayed. +displayed. The Click method is called to signal the OnClick event handler +(when assigned) if the cell is not already selected or displaying a cell +editor.

+ + + + + + + + @@ -15732,8 +15737,26 @@ grid. Cursor shape displayed when a column is resized. - - + +

+ColSizingCursor is a TCursor property with the cursor +displayed when the horizontal size for a column is changed. The default value +for the property is defined in the crHSplit constant. +

+

+It is displayed when a mouse down event causes the grid cursor state to be +changed to the value gcsColWidthChanging. +

+

+Use RowSizingCursor to specify the cursor shape displayed when a row height +is changed. +

+ + + + +crVSplit + @@ -16219,8 +16242,8 @@ grid.

FastEditing is a Boolean property which indicates if -cell editing initialized by a KeyDown message instead of a navigation key is -used in the grid control. The value in FastEditing is used when a +cell editing initialized by a KeyDown message instead of by a navigation key +is used in the grid control. The value in FastEditing is used when a TPickListCellEditor handles KeyDown messages.

@@ -16899,24 +16922,34 @@ control.

Options is a TGridOptions property used to store the options enabled for the grid control. Values from the TGridOptions -enumeration are included in the set type to enable the features or behaviors. +enumeration are included in the set type to enable specific features or +behaviors.

-For the complete list of available options and their usage, see . +The set values can be included or excluded at design-time using the object +inspector in the Lazarus IDE. They can also be included or excluded in the +set at run-time using program code. The default value for the Options +property is defined in the DefaultGridOptions set constant.

-The default value for the Options is the DefaultGridOptions set. +Values present in the set cause the corresponding features or behaviors to be +enabled in the control at run-time. For the complete list of available +options and their usage, see .

-Use Options2 to set scrolling behaviors enabled for the grid -control. +Use Options2 to set scrolling or cell editor behaviors enabled for +the grid control. +

+

+Use MouseWheelOption to control mouse wheel behavior in the grid control.

- - + + + + @@ -17034,7 +17067,9 @@ RangeSelectMode is used in the implementation of methods like: -Row number for the selected grid cell. + +Row number for the selected grid cell. +

Row is an Integer property which contains the row index @@ -17045,15 +17080,24 @@ zero-based, and cannot exceed the value RowCount-1. Setting a new value for the property causes the values in Col and Row to be validated against the ColCount and RowCount for the grid. Error checking is used, and an exception may be raised if the new property value is not in the -limits for the control. The selected cell in the control is changed to the -new values in the Col and Row properties. +limits for the control. The selected cell in the control is changed to (or +extended to) the new values in the Col and Row properties. The Click method +is called to signal the OnClick event handler (when assigned) if the cell is +not already selected or displaying a cell editor.

Use Col to determine the column number for the currently selected cell in the grid control.

- + + + + + + + + @@ -17092,8 +17136,26 @@ Use Col and Row for the current cell selected in the control. Cursor shape displayed when the row height is resized. - - + +

+RowSizingCursor is a TCursor property with the cursor +displayed when the vertical size for a row is changed. The default value for +the property is defined in the crVSplit constant. +

+

+It is displayed when a mouse down event causes the grid cursor state to be +changed to the value gcsRowHeightChanging. +

+

+Use ColSizingCursor to specify the cursor shape displayed when a column width +is resized. +

+ + + + +crVSplit + @@ -17776,15 +17838,15 @@ Application developers can use the OnSelection and OnBeforeSelection events to react to focus changes.

- -??? Component developers should use the ??? method instead. - - + + + + -Event handler signalled to select an Editor control for the current cell. +Event handler signalled to select an Editor control for the current grid cell.

@@ -17836,8 +17898,26 @@ is updated. Event handler signalled to get the user-defined bitmap used for a check box cell. - - + +

+OnUserCheckboxBitmap is a TUserCheckboxBitmapEvent +property with the event handler used to get the user-specified bitmap drawn +for check box cell on the control. It is signalled from the +GetImageForCheckBox method (when assigned) with the control, column, row, and +check box state for the cell. Use the Bitmap argument to return the bitmap +image provided in the event handler routine. +

+

+Use the OnUserCheckboxImage to retrieve an image list and index position with +the graphical representation for a specific check box state. +

+ + + + + + + @@ -17846,21 +17926,52 @@ Event handler signalled to get the user-defined image used for a check box cell. +

+OnUserCheckboxImage is a TUserCheckBoxImageEvent +property with the event handler signalled to get a user-specified image list +and index position for a check box cell with a give state. It is signalled +from the GetImageForCheckBox method (when assigned) with the control, column, +row, and check box state for the cell. Use the ImageList and ImageIndex +arguments to return the image and position provided in the event handler +routine. +

+

+Use the OnUserCheckboxBitmap event handler to get the check box image as a +TBitmap type. +

 - + + + + + + Event handler signalled to perform validation for a cell value.

-OnValidateEntry is a TValidateEntryEvent which -implements the event handler signalled to perform validation for cells in the -ValidateEntry method. +OnValidateEntry is a TValidateEntryEvent property with +the event handler signalled to perform validation for cells in the +ValidateEntry method. The OldValue argument contains the value +validated in the handler routine. Use the NewValue argument to return a +modified value from the handler routine. +

+

+The handler can raise an Exception if needed. It is caught in the calling +routine (ValidateEntry), and forwarded to the HandleException method in the +Application singleton. +

+

+Updated cell values are not validated if the event handler has not been +assigned.

+ +TApplication.HandleException @@ -17937,12 +18048,23 @@ for the grid control. -Event handler signalled when a column is saved in the SaveColumns method. +Event handler signalled when an entry in Columns is saved to a configuration file using the SaveContent method. - + +

+The APath argument contains the XPath-like notation, including the +column identifier, used to access the column definition. For example: +

+ +'grid/design/columns/column1' + + + + + @@ -18510,13 +18632,42 @@ Updates the grid control when the value in a cell Editor is changed. -Finishes an update to the grid control. - - + +Finishes an active update to the grid control. + + +

+EndUpdate is a method used to complete an update started by +calling the BeginUpdate method. +

+

+EndUpdate decrements the internal update counter used in the control. When +the counter reaches 0, there are no other updates active for the control. If +ARefresh is set to True, the VisualChange method is called to update the +cached sizes for the control and Invalidate the control display area. +

+

+BeginUpdate and EndUpdate are used to implement methods like: +

+
    +
  • Assign
    • +
  • AssignTo
    • +
  • Sort
    • +
  • ScrollToCell
    • +
  • DoAutoAdjustLayout
    • +
  • Clean
    • +
  • LoadFromCSVStream
    • +
+ + + + + + -True when the grid control needs to be redrawn in the method. +True causes the grid control to be redrawn using Invalidate. @@ -18646,8 +18797,26 @@ control. Invalidates all cells in the specified column, and causes them to be redrawn. - - + +

+InvalidateCol is a method used to refresh all cells in the column +number specified in the ACol argument. InvalidateCol gets a TRect instance +with the bounds for cells in the specified column number. It calls the +InvalidateRect routine in the LCL interface using the Handle for the control +and the display rectangle as arguments. +

+

+No actions are performed in the method if a Handle has not been allocated in +the widgetset class instance for the control. +

+ +InvalidateCol is not used in the current LCL version. Invalidate is called +instead. + + + + + Column number for the cells invalidated in the method. @@ -18887,25 +19056,52 @@ file system. -Finds the mouse coordinates relative to the grid origin. - - + +Gets the cell coordinates for the specified mouse pointer position. + + +

+MouseCoord is TGridCoord function used to get the +coordinates for the mouse pointer as cell coordinates. It calls the +MouseToCell method to get the TGridCoord (an alias to TPoint) instance used +in the return value. +

+ + + + + - + +TGridCood instance with the cell coordinates for the mouse pointer. + - + +Horizontal screen coordinate for the mouse pointer. + - + +Vertical screen coordinate for the mouse pointer. + -Converts mouse coordinates to the grid coordinates for a cell in the grid. +Converts the specified mouse screen coordinates to cell coordinates. - + +

+MouseToCell is an overloaded method in TCustomGrid used +to convert screen coordinates for the mouse pointer to cell coordinates. One +variant returns the cell coordinates as a TGridCoord (an alias for TPoint) +instance. The other variant returns the cell coordinates as Integer output +parameters. MouseToCell calls the OffsetToColRow method to get the cell +coordinates. +

+ ACol and ARow arguments were changed to output parameters in LCL version 2.1 @@ -18949,23 +19145,62 @@ Converts mouse coordinates to the position for a logical cell in the grid. -Converts the specified mouse position and cell coordinates to the grid zone -where they are located. +Converts the specified coordinates for the mouse pointer to the grid zone where they are located. - - + +

+MouseToGridZone is a TGridZone function used to get the +grid zone where the specified mouse pointer coordinates are located. The +X and Y arguments contain the screen coordinates where +the mouse pointer is located. +

+

+The return value is a TGridZone enumeration value determine by +comparing the screen coordinates to the cached sizes and offsets for the grid +control. The screen coordinates are converted to cell coordinates when +available, and used to the determine the return value. +

+
+
gzInvalid
+
+X and Y are located on the border or in a area not used for cells in the client area for the control. +
+
gzFixedCells
+
+X and Y are located in the fixed header cell (column 0) on the control. +
+
gzFixedRows
+
+X and Y are located in a fixed header cell for a row on the control. +
+
gzFixedCols
+
+X and Y are located in a fixed header cell for a column on the control. +
+
gzNormal
+
+X and Y are located in a non-fixed cell in the display area for the control. +
+
+ + + + - + +Grid zone where the specified mouse pointer coordinates are located. + - + +Horizontal screen coordinate for the mouse pointer. + - - - - + +Vertical screen coordinate for the mouse pointer. + @@ -19146,8 +19381,30 @@ Use ClearSelections to remove the cell rectangles stored in -Number of cell rectangles in the selected range for the grid. - + +Number of cell rectangles in the selected range for the grid. + + +

+SelectedRangeCount is a read-only Integer property with +the number of selected cell rectangles currently selected in the cells for +the control. The property value contains the length of the internal +TGridRectArray maintained in the control + 1 (for the current selected cell +not already in the array). +

+

+Use SelectedRange to access the selection rectangles by the ordinal position +in the the internal TGridRectArray instance. +

+

+Use AddSelectedRange to add a selection rectangle when RangeSelectMode is set +to rsMulti. +

+

+Use ClearSelections to remove all selection rectangles and redraw the grid +control. +

+