Table of Contents

Architecture Overview

(Note: Many of the options and abilities of the SuperGrid, as presented in this document, are demonstrated in the SuperGrid Demo Application included in the DotNetBar Samples folder. Please refer to it as an additional source for information and assistance).

The main functional components to the SuperGrid are as follows:

GridElement – This is the base, root object from which all accessible items within the Grid are ultimately derived.

Several Grid methods and properties return GridElement objects (which may then be cast into their appropriate types – for example, when retrieving the list of currently selected items in the grid – which may be a mixture of Cells, Rows, Columns, or even Panels).

Current GridElement derived objects are as follows:

GridColumn – The basic defining and controlling object for each Column in the grid. All specific column definitions are contained here, including properties such as width, sizing mode, and header text (among many others).

GridColumnHeader – This object defines and controls the basic overall display and interaction with the column header row – the row above the column cell data that displays the individual column header text and image.

GridTextRow – This object is the base defining object for all non-data centric rows within the grid. All the currently defined GridTextRows do not scroll with the grid contents, and are therefore always visible and accessible to the user.

Current GridTextRow derived objects are as follows:

GridCaption– This text row is displayed at the very top of the grid, and is actually rendered outside the bounds of the main body of the grid. All other GridTextRow types are rendered within the bounds of the main grid body.

GridTitle – This text row is again displayed at the top of the grid, below the Caption, but above all other data in the grid.

NonModalEditorCell – Gets the current NonModal cell being edited, or null if no NonModel cell edit is in progress.

PrimaryGrid – Gets the primary, root grid.

SizingStyle – Gets or sets which StyleType (Default, MouseOver, etc) to use for element sizing.

TabSelection – Gets or sets how the TAB key moves the focus when pressed.

VScrollBar – Gets a reference to the grid’s vertical scrollbar.

VScrollMaximum – Gets the vertical scrollbar maximum value.

VScrollOffset – Gets or sets the vertical scrollbar offset.

SuperGridControl Methods

ArrangeGrid()

This routine performs grid layout and arrangement.

You should seldom, if ever, need to call this function. The SuperGrid uses this routine after any grid property has changed that requires the grid layout to be recalculated and its elements arranged. It is provided for external use for those rare instances where you might need to know layout information before the grid has internally called this routine.

BeginUpdate()EndUpdate()

Calling the BeginUpdate routine informs the grid that an extended update phase has begun. The SuperGrid will suspend all layout calculations and display updates until the corresponding EndUpdate routine is called.

BeginUpdate / EndUpdate can be nested and must be called in pairs – every BeginUpdate must also have a matching EndUpdate call.

CancelCapture()

This routine cancels any in-progress operation that may have the mouse caputred (resize, reorder, etc).

This routine attempts to locate a GridPanel with the supplied Name. Each GridPanel has a defined ‘Name’, and though it is not required to be unique, it is advisable. Calling this routine will locate the first GridPanel with the given Name. By default this routine only searches the SuperGrid’s PrimaryGrid defined elements at the root level (ie. it does not search through nested rows or panels). If includeNested is set to ‘true’, the grid will search through all nested rows and panels.

GetElementAt(int x, int y)GetElementAt(Point pt)

This routine gets the GridElement (GridCell, GridRow, GridColumnHeader, etc) at the given coordinates.

GetSelectedCells()

This routine returns a SelectedElementCollection, containing a list of currently selected cells.

The SelectedElementCollection provides you with a mechanism to retrieve a list of every cell that has been selected by the user. It also, via the Select method, can be used to select / or deselect the retrieved list of selected cells.

GetSelectedColumns()

This routine returns a SelectedElementCollection, containing a list of currently selected columns.

The SelectedElementCollection provides you with a mechanism to retrieve a list of every column that has been selected by the user. It also, via the GetCells method, gives you the mechanism to retrieve a non-overlapping list of uniquely selected cells – no matter whether they came from a column or cell collection. You can also use the provided Select method to select / or deselect the retrieved list of selected items.

GetSelectedElements()

This routine returns a SelectedElementCollection, containing a list of currently selected rows, columns, and cells.

There are three units of selection in the SuperGrid – rows, columns, and cells. When you select and entire row, say via clicking on a row’s header, the row selection is tracked via a ‘selected row collection’. The same thing happens when you click on a column header or a cell, the selected column or cell is tracked in a ‘selected column collection’.

The SelectedElementCollection provides you with a mechanism to retrieve a list of every row, column, and cell that has been selected by the user. It also, via the GetCells method, gives you the mechanism to retrieve a non-overlapping list of uniquely selected cells – no matter whether they came from a row, column, or cell collection. You can also use the provided Select method to select / or deselect the retrieved list of selected items.

GetSelectedRows()

This routine returns a SelectedElementCollection, containing a list of currently selected rows.

The SelectedElementCollection provides you with a mechanism to retrieve a list of every row that has been selected by the user. It also, via the GetCells method, gives you the mechanism to retrieve a non-overlapping list of uniquely selected cells – no matter whether they came from a row or cell collection. You can also use the provided Select method to select / or deselect the retrieved list of selected items.

GridContainer

The GridContainer object is the main container object for all row level elements in the SuperGrid. GridContainer elements can be GridPanels or GridRows. GridContainer objects contain a collection of Rows, which are themselves GridContainer objects, and as such can be nested to any desired depth.

The following is a list of the Properties and methods available to all GridContainer elements (GridPanels and GridRows).

Deleted rows are rows “marked for deletion” – they are not permanently deleted until the function PurgeDeletedRows is called. Deleted rows are, by default, automatically hidden when deleted, but this can behavior can be changed via the GridPanel property “AutoHideDeletedRows”.

IsExpandedVisible – Gets whether the row is visible, taking into account all higher level expanded rows. In other words, the given row must be visible – and – if the row is a nested row all parent rows must be both visible and expanded.

IsOnScreen – Gets whether the row is visible on the screen.

IsSelectable – Gets whether the row can be selected by the user.

IsSelected – Gets whether the row is selected.

LastOnScreenRow – Gets the last visible row on the screen.

LastOnScreenRowIndex Gets the index of the last visible row on the screen.

LastSelectableRow – Gets the last row able to be selected by the user.

RowIndex – Gets the sequential, row collection index for the item. Index counting includes both visible and non-visible items.

Rows – The Rows collection for this item. For VirtualMode GridPanels this collection is not used.

RowsUnresolved – Gets or sets whether the Rows collection has been resolved or not.

If this property is set to ‘true’, the SuperGrid will present the user with a row level expand button (if ShowTreeButtons is true), even though the Rows collection is empty. Your application can then hook onto the the BeforeExpandChange event, so that when the user clicks on the expand button it can check the RowsUnresolved property. If the RowsUnresolved property is ‘true’, the application can then dynamically load the Rows collection (and then clear the RowsUnresolved property to signify it has been resolved).

RowStyles – Gets or sets the collection of visual styles for the row.

ShowCheckBox – Gets or sets whether the row level checkBox is shown when the row’s GridPanel.CheckBoxes property is ‘true’.

GridContainer Methods

CollapseAll()CollapseAll(int depth)

Collapses all expanded rows. If a depth is provided, rows will be collapsed only to the given nested depth. In other words, to collapse only the first level of rows in the container, you would call CollapseAll(0). To collapse the first level – as well as 2 levels under it, you would call CollapseAll(2).

EnsureVisible()EnsureVisible(bool center)

This routine will ensure that the row is visible on the screen. If the row is not visible on screen, the view window will be scrolled to make it visible. If the ‘center’ parameter is set to ‘true’, then the row will be centered on screen.

ExpandAll()ExpandAll(int depth)

Expands all collapsed (or unexpanded) rows. If a depth is provided, then rows will be expanded only to the given nested depth. In other words, to expand only the first level of rows in the container, you would call ExpandAll(0). To collapse the first level – as well as 2 levels under it, you would call CollapseAll(2)

ExpandItemTree()

Expands the nested tree, as necessary, to display the given row. Return ‘true’ if any expansion was actually performed.

FindGridPanel()FindGridPanel(bool includeNested)

Searches the Rows collection for a GridPanel with the given Name. If ‘includeNested’ is ‘true’, then nested rows will be included In the search.

GetEffectiveRowStyle()

Gets the ‘Effective’ row style for the row. The ‘Effective’ Style is the cached summation of SuperGrid, Panel, Row, and Alternate Row styles. It is the Style that is used to render each row element for the row.

GetElementAt(int x, int y)GetElementAt(Point pt)

This routine gets the GridElement at the given coordinates.

GetParentPanel()

Gets the parent GridPanel for the item.

IsChildOf(GridContainer row)

Determines whether the row is a child row of the given container row.

IsParentOf(GridContainer row)

Determines whether the row is a parent row of the given container row.

PurgeDeletedRows()PurgeDeletedRows(includeNested)

Purges all rows marked as ‘deleted’. Once rows are purged they cannot be restored. If ‘includeNested’ is ‘true’ then nested rows are also purged.

GridPanel

The SuperGridControl object contains a single root GridPanel (the PrimaryGrid). The GridPanel is the main container for row, column, and cell definitions. GridPanels can have nested rows or GridPanels.

GridPanel Properties

ActiveRow – The current active row (row the user is currently interacting with), or null if no row is defined or active.

ActiveRowImage– The image to display in the row header for the Active Row. By default a small, black right arrow is drawn in the row header. Whether the row indicator is displayed is controlled by the ActiveRowIndicatorStyle property.

ActiveRowIndicatorStyle– Indicates how the Active Row is visually presented in the RowHeader.

The ActiveRowIndicatorStyle can be one of the following:

None – No indicator will be displayed.Image – The “Style based” ActiveRowIndicatorImage will be displayed.Highlight – The Row Header will be highlighted according to the Header Style.Both – The ActiveRowIndicatorImage will be displayed in addition to the header being highlighted.

AllowEmptyCellSelection – Indicates whether empty cells can be selected and interacted with by the user. Empty cells are cells that have been defined via a column definition, but their actual data object (contained within the Row.Cells collection) has not been allocated. If this property is set to ‘true’ then the user may interact with Empty cells via the mouse and keyboard, to select and/or deselect items. It is then at the discretion of the application to decide whether or not to allocate the cells to permit further interaction (Value change, etc).

AllowRowDelete – Indicates whether grid rows can be interactively deleted by the user. If this property is ‘true’ selected rows can be deleted by pressing the ‘delete’ key, and restored by pressing the ‘shift-delete’ key. Deleted rows are only marked for deletion, and not fully deleted until purged (See GridContainer PurgeDeletedRows).

AllowRowHeaderResize – Indicates whether the grid row header can be resized by the user.

AllowRowInsert – Indicates whether grid rows can be interactively inserted by the user. Rows can be inserted by selecting a row and pressing the ‘insert’ key. When a new row is inserted, each cell in the row is populated with its DefaultNewRowCellValue as defined by the cell’s associated column. If the RowSetDefaultValues event is hooked, then the application is given another opportunity to set the default values for each cell.

AllowRowResize – Indicates whether grid rows can be interactively resized by the user.

AutoGenerateColumns – Indicates whether columns are created automatically when the DataSource property is set.

CanDeleteRow – Indicates whether row deletes are permitted. Row deletions may not be permitted due to several factors, such as whether the AllowRowDelete property is true, Grouping is in effect, or the bounds data source allows or disallows it.

CanInserrtRow – Indicates whether row inserts are permitted. Row insertions may not be permitted due to several factors, such as whether the AllowRowInsert property is true, Grouping is in effect, or the bounds data source allows or disallows it.

CanMoveRow – Indicates whether row moving is permitted. Row moves may be disallowed if the panel’s RowDragBehavior is not set to Move, or the panel is in Virtual Mode, or the panel is bound to a DataSource.

Caption – Indicates the Caption item, which is displayed at the very top of the panel. The Caption is fixed and it does not move as grid rows are scrolled.

CellDragBehavior – Indicates the behavior when a cell is clicked and dragged. The behavior may be one of the following:

None – Dragging will have no effect.ExtendSelection – Dragging will extend the selection.

Note: This property does not effect Drag and Drop types of operations. If the application needs to support Drag and Drop, the ItemDrag event can be utilized to initiate a Drag and Drop operation on the given cell (or range of cells) – independent of the current set CellDragBehavior.

CheckBoxes – Indicates whether CheckBoxes are present in the grid rows. If this property is ‘true’ then CheckBoxes will be displayed in the PrimaryColumn of each row. If the row is a GridPanel row, then the CheckBox is placed external, to the left of the panel. CheckBox display can be controlled for each individual row via the row’s ShowCheckBox property. Row level CheckBoxes are not used internally by the SuperGrid for any purpose, and the check state significance is solely defined by the application.

CheckBoxSize – Indicates the Row level CheckBox Size.

CollapseImage – Indicates the default TreeButton collapse image. If the ShowTreeButtons property for the panel is ‘true’, then when a row contains nested rows, its Primary column will contain a button that will permit the expansion and collapse of the display of the nested rows. When the nested rows are hidden (or collapsed) then the ExpandImage will be shown. When the nested rows are shown (or expanded) then the CollapsImage is shown. Setting the CollapseImage property permits the application to set a unique image to be displayed in the place of the default collapse image. Setting the value to null will reset it back to the default.

Fill – The column width adjusts so that the widths of all columns exactly fills the display area of the control, requiring horizontal scrolling only to keep column widths above the ColumnHeader.MinimumWidth property values. Relative column widths are determined by the relative Column.FillWeight property values.

DisplayedCellsExceptHeader – The column width adjusts to fit the contents of all cells in the column that are in rows currently displayed on screen, excluding the header cell.

DisplayedCells – The column width adjusts to fit the contents of all cells in the column that are in rows currently displayed on screen, including the header cell.

ColumnHeader – The column width adjusts to fit the contents of the column header cell.

AllCellsExceptHeader – The column width adjusts to fit the contents of all cells in the column, excluding the header cell.

AllCells – The column width adjusts to fit the contents of all cells in the column, including the header cell.

ColumnHeader – Gets a reference to the Column Header for the grid panel. The Column Header is the container object responsible for the definition and control of the Column Header row (container each column header text, etc).

ColumnHeaderClickBehavior – Indicates the behavior when a column header is clicked. The behavior can be set to one of the following items:

None – Clicking on a column header will have no effect.

Select – Clicking on a column header will select the column, and dragging will extend the selection (if Column.ColumnDragBehavior is set to ExtendClickBehavior).

SortAndReorder – Clicking on a column header will sort the grid using that column, or will reorder the column (if Column.ColumnDragBehavior is set to ExtendClickBehavior).

ColumnDragBehavior – Indicates the behavior when a column header is dragged. The behavior can be set to one of the following items:

None – Dragging on a column header will have no effect.

ExtendClickBehavior – Dragging a column header will extend the set ColumnHeaderClickBehavior.

Columns – Gets a reference to the collection of grid columns.

DataMember – Indicates the name of the list or table in the data source that the grid is bound to.

DataSource – Indicates the data source that the grid is bound to. The SuperGrid can bind to any data source that supports the IList, IListSource,or IBindingList interface.

DefaultRowHeight – Indicates the row height to be used for each data row in the grid (default is 20). The SuperGrid supports row autosizing, where the row height is dynamically determined based upon various characteristics gathered from each cell in the row (font, wrap mode, image placement, etc). To enable row autosizing, set this value to ‘0’ (zero).

DefaultVisualStyles– Contains the default visual styles for each main element in the SuperGrid. See DefaultVisualStyles in the SuperGridControl property listing for a further breakdown of the individual properties contained within this item.

DeletedRowCount – Indicates the current number of deleted rows.

DeletedRows – IEnumerable that can be used to enumerate through all root level deleted rows. Use FlatDeletedRows to enumerate through all levels of deleted rows.

The SuperGrid not only supports bound and unbound cell data, but also supports Excel-like cell expression evaluation. All cell expressions must begin with an equal sign “=”, followed by a normal arithmetic expression. See the Cell Expressions section for a more detailed description of the Cell Expression support.

EnsureVisibleAfterSort – Gets or sets whether EnsureVisible will be called for the current ActiveRow following a sort operation.

EnterKeySelectsNextRow – Indicates whether the EnterKeyselects the next available row, or stays on the current row.

ExpandImage – Indicates the default TreeButton expand image. If the ShowTreeButtons property for the panel is ‘true’, then when a row contains nested rows, its Primary column will contain a button that will permit the expansion and collapse of the display of the nested rows. When the nested rows are hidden (or collapsed) then the ExpandImage will be shown. When the nested rows are shown (or expanded) then the CollapsImage is shown. Setting the ExpandImage property permits the application to set a unique image to be displayed in the place of the default expand image. Setting the value to null will reset it back to the default.

FirstVisibleColumn – Gets a reference to the first visible column.

FlatDeletedRows – IEnumerable that can be used to enumerate through all levels of deleted rows as though they were at the root level. Use DeletedRows to enumerate through only root level deleted rows.

FlatExpandedRows – IEnumerable that can be used to enumerate through all levels of expanded rows as though they were at the root level.

FlatRows – IEnumerable that can be used to enumerate through all levels of rows as though they were at the root level.

FlatVisibleExpandedRows – IEnumerable that can be used to enumerate through all levels of visible, expanded rows as though they were at the root level.

FlatVisibleRows – IEnumerable that can be used to enumerate through all levels of visible rows as though they were at the root level.

Footer – Indicates the Footer item, which is displayed at the very bottom of the panel. The Footer is fixed and does not move as grid rows are scrolled.

FrozenColumnCount – Indicates the number of columns that are frozen, counted from the left. Frozen columns do not scroll, but rather are always visible regardless of the horizontal scroll position.

FrozenRowCount – Indicates the number of rows that are frozen, counted from the top. Frozen rows do not scroll, but rather are always visible regardless of the vertical scroll position.

GridLines – Indicates which grid lines are displayed in the grid. The possible settings for this property are as follows:

None – No grid lines are displayed.Horizontal – Only horizontal grid lines are displayed.Vertical – Only vertical grid lines are displayed.Both – Both horizontal and vertical grid lines are displayed.

GroupHeaderClickBehavior – Indicates the behavior when a Group header is clicked. The possible settings for this property are as follows:

None – Clicking on a group header will have no effect.ExpandCollapse – Clicking on a header will expand or collapse the group.Select – Clicking on a group heading will select the header.SelectAll – Clicking on a group heading will select all the first-level rows contained in the group.

GroupHeaderKeyBehavior – Indicates the behavior when a Group header is encountered during keyboard navigation. The possible settings for this property are as follows:

Skip – Header will be skipped.Select – Header will be selected.

GroupHeaderHeight – Indicates the height of the Group header. Default is 30.

GroupRowHeaderVisibility – Indicates whether the Group RowHeader is displayed. The possible settings for this property are as follows:

Header – Indicates the Headeritem, which is displayed just below the column header. The Header item is fixed and does not move as grid rows are scrolled.

ImageList – Indicates the ImageList used by the Grid elements. Used by Panel.InsertRowImageIndex, CellVisualStyle (ImageIndex) and RowHeaderVisualStyle (ActiveRowImageIndex, EditingRowImageIndex, and InfoRowImageIndex).

ImmediateResize – Indicates whether resizing panel rows and columns and occurs in immediately, or real-time. If this property is false, then element resize operations are denoted by a marker element, and the resize occurs after the mouse is released.

IndentGroups – Indicates whether Nested Groups are indented.

InitialActiveRow – Indicates the initial Active Row. The active row does not denote selection (to specify how what to initially select, see the following InitialSelection property). The possible settings for this property are as follows:

None – No row is to be made active.FirstRow – First row is to be made active.InsertionRow – The insertion row is to be made active.LastRow – The last row in the grid is to be made active.

InitialSelection – Indicates the initial row / cell selection. The initial selection does not denote activation (to specify how what to initially make active, see the prior InitialActiveRow property). The possible settings for this property are as follows:

InsertRowImage– Indicates the default image to display in the row header to denote the Insertion Row.

InsertRowImageIndex – Indicates the Insert Row image index. This index, when set, is used in conjunction with the GridPanel.ImageList to define the image to use in the Insert Row header.

IsSortable – Gets whether the grid is able to be sorted.

IsSubPanel – Gets whether the grid panel is a sub-panel of another grid panel.

KeyboardEditMode – Indicates how cell editing is initiated by the keyboard. The KeyboardEditMode can be set to one of the following values:

None – No keyboard action will initiate an edit.EditOnKeystroke – Edit initiated when any alphanumeric key is pressed while the cell has focus.EditOnF2 – Edit initiated when F2 is pressed while the cell has focus. This mode places the selection point at the end of the cell contents.EditOnKeystrokeOrF2 – Editing begins when any alphanumeric key or F2 is pressed while the cell has focus.EditOnEntry – Editing begins on entry to a cell.

LastVisibleColumn – Gets a reference to the last visible column.

LevelIndentSize– Indicates the amount to indent the grid data when a new grid level is encountered. The default height is 10, and the default width is 20.

RowDoubleClickBehavior – Indicates the behavior when a row is double clicked. The possible settings for this property are as follows:

Activate – The row is activated.ExpandCollapse – The row is expanded or collapsed.

RowDragBehavior – Indicates the behavior when a row header is clicked and dragged. RowDragBehavior can be one of the following values:

None – Dragging on a row header will have no effect.ExtendSelection – Dragging a row header will extend the selection.Move – Dragging a row header will initiate a row move that will be constrained to stay within the current row group.GroupMove – Dragging a row header will initiate a row move that can cross group row boundaries.

RowEditMode – Gets or sets whether editing is initiated on the primary cell (cell in the Primary Column) or the clicked cell (cell under the mouse when row level editing is initiated). RowEditMode can be one of the following:

RowHeaderWidth – Gets or sets the width of the row header for each row in the grid.

RowHighlightType – Gets or sets the type of highlighting to use when a row is selected. This property can be one of the following values:

None – No highlighting.Full – The entire row will be Highlighted.PrimaryColumnOnly – Only the Primary Column cell contents will be Highlighted.

RowWhitespaceClickBehavior – Gets or sets the behavior when the user clicks the mouse in the row whitespace. Row Whitespace is the area of the row that extends past the end of the last defined column. RowWhitespaceClickBehavior values can be one of the following:

ShowRowDirtyMarker – Gets or sets whether the DirtyRow marker is displayed, signifying that the row data has been changed by the user. Row data changes can occur via cell Value changes or via the row checkbox state changing.

ShowToolTips – Gets or sets whether tooltips are shown for cell data that is truncated by the display.

ShowTreeButtons – Gets or sets whether expand / collapse buttons are shown for rows containing nested rows. The TreeButtons, along with the associated TreeLines, are only displayed in the current set Primary Column.

ShowTreeLines – Gets or sets whether hierarchical tree-lines are shown connecting grid rows. The TreeLiness, along with the associated TreeButtonss, are only displayed in the current set Primary Column.

SizingStyle – Gets or sets which Visual Display Style to use for element sizing. When calculating the determinate cell size for a given cell, this property will define which visual style to use. This can be useful when one style results in a larger calculated size than the default. For example, if the application wants to have its cells use a MouseOver style with a font that is 2 points larger than the default visual style, it would be nice to have the cell size calculated according to the MouseOver style, not the default style.

SortColumns – Gets a reference to the list of columns to use for sorting the grid data

SortLevel – Gets or sets the column sorting level. Here is a list of how the rows are sorted for each available SortLevel value:

None – No sorting is performed.Root – Only the root-level row data is sorted. All nested row data is left unsorted.Expanded – Only expanded nested rows are sorted. The root-level rows are left unsorted.All – All rows are sorted – both root-level and nested.

Title – Gets or sets the Title item which is displayed just above the Column Header. The Title area is fixed and it does not move as grid rows are scrolled.

TopLeftHeaderSelectBehavior – Gets or sets the behavior that occurs when the top left header is selected by the user. TopLeftHeaderSelectBehavior can be one of the following values:

NoSelection – No selection.SelectAllCells – No selection.SelectAllColumns – All columns will be selected.SelectAllRows – All rows will be selected.Deterministic – Element selection will be determined by the current set SelectionGranularity.

VirtualMode – Gets or sets whether the grid data is virtualized (ie. external to the grid). The panel’s Row collection is not used when VirtualMode is true. Rather the VirtualRowCount property defines now many external rows are defined. In a like manner, the VirtualRowHeight property determines the row height, not the DefaultRowHeight property.

VirtualRowCount – Gets or sets the number of external virtual grid rows.

VirtualRowHeight – Gets or sets the height of every virtual row. The default is 20.

VisibleColumnCount – Gets the current visible column count.

VisibleRowCount – Gets the current visible row count.

WhitespaceClickBehavior – Gets or sets the behavior when the user clicks the mouse in the grid panel whitespace area. The following is a list of valid values for this property:

This routine is used to add an individual Column, or an array of Columns (along with either a general or column specific sort direction), to the list of columns used to sort grid data rows.

ClearAll()

Clears all cells, rows, and columns from their associated selection lists. Each selectable element is maintained in its own selection list or collection. Cell, row, and column selections can therefore overlap and/or intersect. Clearing the Cells collection alone will not effect the fact that every column may also be selected. This routine clears all selection lists such that no element is selected following this call.

ClearGroup()

Clears all currently set Column Groups.

ClearSelectedCells()

Clears all currently selected Cells. See ClearAll for further notes.

ClearSelectedColumns()

Clears all currently selected Columns. See ClearAll for further notes.

Copies the currently selected list of tab delimited (unless an alternate delimiter is specified) cells to the system ClipBoard. This routine takes all cell, column, and row selections into account when determining what cell data to write to the clipboard.

DeleteAll()

This routine marks each data rows as Deleted. Data rows are only marked for deletion, and are not actually removed from the Rows list until they are purged via the PurgeDeletedRows method.

DetachDataSource(bool keepData)

Detaches the grid from the previously bound DataSource. If ‘keepData’ is true, then the data is kept (but no longer bound).

GetColumnAt(Point point)

Gets the GridColumn containing the specified location, or null if no Column contains the given location.

GetDeletedRows()

Gets a SelectedElementCollection of the current list of Deleted Rows.

GetElementAt(int x, int y)GetElementAt(MouseEventArgs e)

Gets the current panel element at the given location.

GetRowFromIndex(int gridIndex)

Gets the GridContainer / Row from the given GridIndex.

GetSelectedCells()

Gets a SelectedElementCollection containing a list of currently selected cells.

GetSelectedColumns()

Gets a SelectedElementCollection containing a list of currently selected columns.

GetSelectedElements()

Gets a SelectedElementCollection containing a list of currently selected rows, columns, and cells.

GetSelectedRows()

Gets a SelectedElementCollection containing a list of currently selected rows.

InsertRow(int index)

Inserts a new row at the given index.

InvalidateRender()

Invalidates the display state of the panel.

IsCellSelected(int rowIndex, int colIndex)

Retrieves whether the given cell (as specified by the given row and column index) is selected.

IsColumnSelected(int colIndex)

Retrieves whether the given column (as specified by the given column index) is selected.

These routines are used to set an individual Column, or an array of Columns (along with either a general or column specific sort direction), to the list of columns used to group grid data rows together. All previous grouping is replaced with the new settings.

These routines clear the current list of sorting columns (with their associated sorting directions – i.e. ascending or descending), and set it to the provided list of columns (with their associated sorting directions ). If no SortDirection is provided, then SortDirection.Ascending is used by default.

ToggleMultiColumnSort()

This routine toggles the current sort direction for the current list of sort columns.

UnDeleteAll()

Un-deletes (or restores) all previously deleted grid rows.

GridRow

The GridPanel contains a collection of rows (Rows) that define each row of cell data, as well as specifying certain default characteristices and behavior for all cells contained within the given row. A row’s defined cells can be accessed via row.Cells[columnIndex], row.Cells[“ColumnName”], row[columnIndex], row[“ColumnName”], or row[GridColumn].

GridRow Properties

Bounds – Gets the scroll adjusted bounds of the row.

Cells – Gets a reference to the Cells (GridCell) collection. Cells in the Cells member are not allocated by default, but are only done so if the cell Values are provided to the GridRow constructor at row allocation time. Row cells can be allocated later, and assigned (or added) to the current Cells collection. Note that the cells are sequentially allocated, thus you can not allocate and assign Cell 10 without also having allocated and assigned cells 0 through 9.

DataItem – Gets the object to which the row is bound.

EditorDirty – Gets or sets whether the value being edited has changed.

FirstSelectableCell – Gets a reference to the first selectable cell or null if there is none defined.

FirstVisibleCell – Gets a reference to the first visible cell or null if there is none defined.

InfoText – Gets or sets the informational text associated with the row. If the InfoText is non-null, then the row’s associated InfoImage is displayed in the RowHeader, with the InfoText being displayed as the ToolTip for the InfoImage.

IsDeleted – Gets or sets whether the row has been marked as deleted. Deleted rows are not permanently removed from the grid until they are purged (see PurgeDeletedRows).

IsInsertRow – Gets whether the row is the InsertRow.

LastSelectableCell – Gets a reference to the last selectable cell or null if there is none defined.

LastVisibleCell – Gets a reference to the last visible cell or null if there is none defined.

RowDirty – Gets or sets whether the row state has changed.

RowHeight – Gets or sets the height of the row (0 denotes AutoSize, -1 denotes NotSet). Setting the value to –1 will cause the grid to use the panel’s DefaultRowHeight for the row’s height.

SelectedCells – Gets an array of the currently Selected Cells.

WhiteSpaceBounds – Gets the bounding rectangle for the area past the end of the last defined column.

GridRow Methods

GetCell(int columnIndex)GetCell(int columnIndex, bool includeEmpty)

This routine gets the Row Cell for the given column index. If “includeEmpty” is true, and the cell does not exist (ie. is empty), then a dummy empty cell will be created and returned. All changes made to an empty cell (denoted by cell.IsEmpty), will not effect permanent changes, and will ultimately be discarded.

GetHitArea(Point pt)

This routine gets the RowArea ‘HitArea’ containing the given point (e.g. InCellCheckBox, InCellExpand, InRowHeader, etc).

GetMaximumRowHeight()
GetMaximumRowHeight(GridColumn[] columns)

This routine calculates and returns the maximum row height based upon the individual measured heights of each cell in the row. If an array of columns is provided, then only those columns will be included in the calculation process. If no columns are given, then all visible columns are utilized.

GetNextVisibleCell(GridCell cell)

This routine returns the next visible cell in the row, after the given cell. If the given cell is null, the first visible cell in the row will be returned.
GetPrevVisibleCell(GridCell cell)

This routine returns the previous visible cell in the row, prior to the given cell. If the given cell is null, the last visible cell in the row will be returned.

The GridRow constructor will create and initialize a new GridRow object. If a single text value is supplied then a single GridCell will be allocated and it’s Value will be set to the given text value. If an array of GridCells is provided, then each cell in the array will be added to the row’s Cells collection. If an array of objects, or a list of parameters, is provided, then for each item in the list a new GridCell will be allocated and initialized to the given value.

GridColumn

The GridPanel contains a collection of columns (Columns) that define not only the horizontal placement of the columnar cell data, but specify certain default characteristices and behavior for all cells contained within the given column. Each of the columns defined in the GridPanel are objects of type GridColumn. A Panel’s defined columns can be referenced via panel.Columns[index] or panel.Columns[“Name”].

GridColumn Properties

AdjustSortImagePositionByMargin – Gets or sets whether the Column Header sort image position is adjusted by the header margin.

AutoSizeMode– Gets or sets how column auto-sizing is performed.

NotSet – Defaults to the current Panel setting.

None – Auto-sizing does not take place.

Fill – The column width adjusts so that the widths of all columns exactly fills the display area of the control, requiring horizontal scrolling only to keep column widths above the ColumnHeader.MinimumWidth property values. Relative column widths are determined by the relative Column.FillWeight property values.

DisplayedCellsExceptHeader – The column width adjusts to fit the contents of all cells in the column that are in rows currently displayed on screen, excluding the header cell.

DisplayedCells – The column width adjusts to fit the contents of all cells in the column that are in rows currently displayed on screen, including the header cell.

ColumnHeader – The column width adjusts to fit the contents of the column header cell.

AllCellsExceptHeader – The column width adjusts to fit the contents of all cells in the column, excluding the header cell.

AllCells – The column width adjusts to fit the contents of all cells in the column, including the header cell.

Bounds – Gets the scroll adjusted bounds of the Column.

CellHighlightMode – Gets or sets the type of highlighting to perform when a cell is selected. CellHighlightMode can be one of the following values:

None – No highlighting will take placed.

Full – The entire cell will be highlighted.

Partial – Only a partial portion of the cell will be highlighted (ie. the entire area excluding the cell / column defined image).

Content – The cell contents only will be highlighted (ie. only the textual / control area of the cell).

CellStyles – Gets or sets the default visual styles assigned to the column cells. The cell styles defined in this property will be taken as the default visual styles for every cell contained in the given column. The cell itself can redefines any / all of these column level styles.

ColumnSortMode – Gets or sets how column sorting is performed. This property can be oe of the following values:

None – No sorting is permitted.

Single – Column can participate in single column sorts only.

Multiple – Column can participate in single and multiple column sorts.

DataPropertyName – Gets or sets the name of the data source property or database column to which the column is bound.

DefaultNewRowCellValue – Gets or sets the default cell value used when a new row is added. When a new row is added, either by the user pressing the row level insert key, or by interaction with the InsertRow, or by programmatically calling panel.InsertRow, the SuperGrid will set the default value for each cell in the row to the cell’s associated column DefaultNewRowCellValue. After establishing each cell’s default values via this property, the SuperGrid will then raise the DoRowSetDefaultValuesEvent, giving you the ability to dynamically alter the cell’s default value as needed.

DisplayIndex – Gets or sets display index of the column. A lower display index means a column will appear first (to the left) of columns with a higher display index. Allowable values are from 0 to num columns – 1. (-1 is legal only as the default value). SuperGrid enforces that no two columns have the same display index (ie. changing the display index of a column will cause the index of other columns to adjust as well).

EditControl – Gets the default Edit Control used for each cell in the column. The column level edit control is a shared control, created and based upon the column level EditorType and EditorParams properties. Each cell in the column, that does not define its own EditorType, will utilize the column level EditControl.

EditorParams – Gets or sets an array of arguments that match in number, order, and type the parameters of the EditControl constructor to invoke. If empty or null, the default constructor is invoked.

Example – C#

// Set the ImageEdit column EditorType to our EditControl type

// so that we can send it the ImageList and SizeMode to use

GridColumn column = panel.Columns["ImageEdit"];

column.EditorType = typeof(MyGridImageEditControl);

column.EditorParams = newobject[] { imageList1, ImageSizeMode.Zoom };

Example – VB

' Set the ImageEdit column EditorType to our EditControl type

' so that we can send it the ImageList and SizeMode to use

Dim column As GridColumn = panel.Columns("ImageEdit")

column.EditorType = GetType(MyGridImageEditControl)

column.EditorParams = NewObject() { imageList1, ImageSizeMode.Zoom }

EditorType – Gets or sets the default cell editor type. This is the default control type used to perform the actual modification or display interaction of the cell value.

FillWeight – Gets or sets a value which represents the width of the column relative to the widths of other fill-mode columns (default value is 100).

When the AutoSizeMode property value is ‘Fill’, the column is resized, along with other columns in that mode, so that all visible columns in the grid exactly fill the horizontal width of the available display area. All fill-mode columns in the grid divide the available space in proportions determined by their FillWeight property values.

RenderControl – Gets the default Render Control used for each cell in the column. The column level render control is a shared control, created and based upon the column level RenderType and RenderParams properties. Each cell in the column, that does not define its own RenderType, will utilize the column level RenderControl.

RenderParams – Gets or sets an array of arguments that match in number, order, and type the parameters of the RenderControl constructor to invoke. If empty or null, the default constructor is invoked. (See EditorParams for example code).

RenderType – Gets or sets the cell render control type (defaults to EditorType, when not set).

ResizeMode – Gets or sets how the column is resized by the user. This property can be one of the following values:

None – The column cannot be resized.

MaintainTotalWidth – The size of the column, plus that of its adjacent column, is changed so that the total size of the columns is maintained.

MoveFollowingElements – When the column size is changed, all following columns are offset accordingly.

SelectedCellCount – Gets the current count of selected cells in the column.

SortIndicator – Gets or sets the sort indicator. This value can be one of the following items:

None – No indicator is displayed.

Ascending – The Ascending Indicator is displayed.

Descending – The Descending Indicator is displayed.

Auto – The Indicator is set automatically, based upon the current column sort criteria.

Width – Indicates the column width (default is 100).

GridColumn Methods

GetMaximumCellSize(RowScope scope, bool includeHeader)

This routine calculates and returns the maximum cell size from each cell in the column, as limited by the given row scope (‘AllRows’ or ‘OnScreenRows’). If ‘includeHeader’ is true, then the width of the header is included in the max calculation.

GetSelectedCells()

This routine returns a SelectedElementCollection containing a list of currently selected cells.

GridColumn()
GridColumn(string name)

GridColumn constructor, optionally taking the column Name as a parameter.

ToggleSort()

This routine toggles the sort direction for the column.

GridCell

Each GridRow rows contain a collection of Cells that define specific cell data, but specify certain default characteristices and behavior for the individual cell.

EditControl – Gets the Edit Control used for the cell. The cell level edit control is a non-shared control, created and based upon the cell level EditorType and EditorParams properties.

EditorDirty– Gets or sets whether the value being edited has been changed in the editor.

EditorParams– Gets or sets an array of arguments that match in number, order, and type the parameters of the EditControl constructor to invoke. If empty or null, the default constructor is invoked.

EditorType– Gets or sets the cell editor type. This is the control type used to perform the actual modification or display interaction of the cell value.

ExpValue– Gets the last evaluated expression value for the cell.

GridColumn– Gets the GridColumn associated with the cell.

GridRow– Gets the GridRow associated with the cell.

HighLightBounds– Gets the scroll adjusted, bounding rectangle used to highlight the cell contents when selected.

InfoImage– Gets or sets the cell informational Image (the image to display when InfoText is non-empty).

InfoImageBounds– Gets the scroll adjusted, bounding rectangle for the current set InfoImage.

InfoText– Gets or sets the informational text associated with the cell. If the InfoText is non-null, then the cell’s associated InfoImage is displayed in the cell, with the InfoText being displayed as the ToolTip for the InfoImage.

IsReadOnly– Gets whether the cell is Read Only due to row, column, or cell ReadOnly property status.

IsSelectable– Gets whether the cell is selectable due to row, column, or cell AllowSelection property status.

IsSelected– Gets or sets whether the cell is selected.

IsValueExpression– Gets whether the cell Value is an expression.

NullString – Gets or sets the text to display for null values.

ReadOnly– Gets or sets whether the user can change cell contents.

RenderControl – Gets the Render Control used for the cell. The cell level render control is a non-shared control, created and based upon the cell level RenderType and RenderParams properties.

RenderParams – Gets or sets an array of arguments that match in number, order, and type the parameters of the RenderControl constructor to invoke. If empty or null, the default constructor is invoked. (See EditorParams for example code).

RenderType – Gets or sets the cell render control type (defaults to EditorType, when not set).

Value– Gets or sets the cell value.

GridCell Methods

BeginEdit(bool selectAll)

Begins a Modal cell edit operation using the defined column or cell Modal EditControl. This routine only operates on Modal edit control types. There must also not be any current modal cell operation in progress.

CancelEdit()

This routine cancels the current in-progress Modal cell edit operation

CellRender(IGridCellEditControl editor, Graphics g)

This routine can be called by a cell editor / renderer to perform default cell rendering provided by the grid

EditorValueChanged(IGridCellEditControl editor)

This routine is called by cell editors to signal to the grid that the editor has changed the cell Value.

EndEdit()

This routine ends an in-progress Modal cell edit operation.

EnsureVisible(bool center)

Ensures that the given cell is visibly centered (as much as possible) in the grid display.

GetCellEditBounds(IGridCellEditControl editor)

Get the CellEditBounds for the cell.

GetEffectiveStyle()

Gets the EffectiveStyle for the cell. The effective style is the cached, composite style definition for the given cell, composed from panel, row, column, and cell styles.

GetExpValue(string sval)

Gets the resultant value of the evaluated Cell Expression, if applicable. Otherwise returns the given value.

GridCell()

GridCell(object value)

Constructors for the GridCell object. If a value is supplied, then the cell Value is set to that value, otherwise the Value is null.

PaintEditorBackground(PaintEventArgs e, IGridCellEditControl editor)

This routine performs default cell background painting for the cell.

SetEditorDirty(IGridCellEditControl editor)

Called by the cell editor to conditionally set the cell’s row level EditorDirtystate.

Grid Cell Interaction

There are no dedicated Column classes or Column-Cell component pairs that must be allocated and assigned to support the underlying cell data. Rather the SuperGrid displays and interacts with the user via ‘Cell Editors and Renderers’.

Each Column has an ‘EditorType’ property that defines the editor that is used by default for each cell in that specific column. This property takes the ‘typeof’ the editor, and is used by the SuperGrid to instantiate the editor for the cells to use in the cell edit process. In a like fashion, the column also has a ‘RenderType’ property that serves the same function as the EditorType property, but is used solely for cell rendering.

Each Cell also has an EditorType and RenderType property that, if set, will override the Column settings for these same properties. So, it is possible for every cell in a given column to have their own unique editor and / or renderer, if the application requires it. Both the Cell Editor and Renderer can also be set dynamically via the GetEditor and GetRenderer events.

Here is a column from one of the sample applications where the cell renderer has been set to a GridTextBoxXEditControl in some cells, and a GridCheckBoxExEditControl in others. The sample also has the Column Editor set to GridCheckBoxExEditControl as well.

There are three basic modes of interaction that a cell editor/renderer may utilize in the SuperGrid. Each mode defines a specific method of interaction in the way cell data is both rendered and edited in the grid. The three modes are as follows:

InPlace – This mode causes the grid to treat the editor/renderer as though it were instantiated and always active in the cell. There are no transitional states that are required for either rendering or editing.

Model – This mode is characterized by the fact that in order to edit the control, a modal state must be entered and exited. With this mode, the SuperGrid displays the formatted textual data, but the actual editing process occurs by the editor when the user specifically enters an edit state (via double click, f2, etc).

NonModal – This mode is somewhat of a mixture of the InPlace and Modal editor modes. The cell rendering happens the same as InPlace rendering, but the edit process is immediately initiated when the mouse enters the cell – and automatically ended when it is left.

Here is a table of each of the SuperGrid’s currently defined editors, and the mode under which they operate.

Editor / Renderer

Editor Mode

GridBubbleBarEditControl

Modal

GridButtonXEditControl

NonModal

GridCheckBoxXEditControl

InPlace

GridComboBoxExEditControl

Modal

GridDateTimeInputEditControl

Modal

GridDateTimePickerEditControl

Modal

GridDoubleInputEditControl

Modal

GridGaugeEditControl

InPlace

GridImageEditControl

InPlace

GridIntegerInputEditControl

Modal

GridIpAddressInputEditControl

Modal

GridLabelXEditControl

InPlace

GridMaskedTextBoxEditControl

Modal

GridMicroChartEditControl

InPlace

GridNumericUpDownEditControl

Modal

GridProgressBarXEditControl

InPlace

GridRatingStarEditControl

InPlace

GridSliderEditControl

InPlace

GridSwitchButtonEditControl

InPlace

GridTextBoxDropDownEditControl

Modal

GridTextBoxXEditControl

Modal

Creating Your Own Grid Cell Editors / Renderers

The SuperGrid provides several (20+) cell editors / renderers (TextBoxX, CheckBoxX, ButtonX, etc) for you to use in the editing and presentation of your cell data. You can also, if none of the provided editors perfectly fits your needs, create your own. Most every Windows Control can be used to create a SuperGrid Cell Edit Control by simply sub-classing the Control and supporting the IGridCellEditControl interface.

IGridCellEditControl Properties

CanInterrupt– Gets whether the Grid can automatically interrupt the current NonModal cell edit operation when the mouse leaves the cell.

This is utilized in cases, such as the ButtonX editor, where multilevel controls may be involved. In the ButtonXcase this specifically enables the mouse to to leave the main cell window and not be interrupted by the grid until the current operation is complete by the editor itself.

CellEditMode– Gets the cell editor activation mode. There are three modes available for choice, and their usage depends upon the desired editor presentation, as well as how well the given underlying control interacts with the grid control.

The modes are as follows:

InPlace – Edit operations occur ‘in place’, always live, always in a state of interaction with the user. The CheckBoxEx, and Slider editors are examples of this.

Modal – Edit operations will be performed as a modal, widowed edit controlled via calls to BeginEdit, EndEdit, and CancelEdit. The TextBoxEx and IntegerInput editors are examples of this.

NonModal – Edit operation will be performed as a nonModal, windowed edit, automatically invoked upon entry to the cell. The ButtonEx and BubbleBar editors are examples of this.

EditorValueChanged– Gets or sets whether the editor value has changed.

EditorValueType– Gets the editor’s default value data type.

StretchBehavior– Gets the editor’s desired ‘stretch’ behavior. The StretchBehavior defines whether the editor wants to automatically have it’s size stretched to fill the given cell. Editors, such as ButtonX, want to fill the cell horizontally and vertically, whereas other editors, such as the Slider, may only want to stretch horizontally (or potentially not at all).

SuspendUpdate– Gets or sets whether updates to the grid state are (or should be) suspended.

ValueChangeBehavior– Gets the behavior needed when a value changes in the editor. For instance, CheckBoxExValue changes require only the cell to be redisplayed with the new state, whereas editors such as the TextBoxXeditor, may result in a new layout when the text changes.

IGridCellEditControl Methods

CellRender(Graphics graphics)

Called to initiate the actual rendering of the editor value into the grid cell. In most cases this can be (and is) handled by a simple call to EditorCell.CellRender(this, graphics). If additional rendering is required by the editor, then the editor can completely render the cell contents itself (and never even call Editor.CellRender) or optionally perform additional rendering before or after the default cell rendering.

CellKeyDown(KeyEventArgs e)

Called when a KeyDown occurs and the CellEditMode is not Modal (otherwise the key event is automatically directed straight to the editor control).

BeginEdit(bool selectAll)

Called when a Modal cell edit is about to be initiated. SelectAll set to ‘true’ signifies whether to select all editable content upon invocation. The editor can cancel the edit operation by returning ‘true’ from this call.

CancelEdit()

Called when the edit operation is being cancelled. The editor can cancel the cancel operation by returning ‘true’ from this call.

EndEdit()

Called when the edit operation is about to end. The editor can cancel the end operation by returning ‘true’ from this call.

I do not know exactly what you mean by “pagination”, however if you are adding 40,000 records to your grid – and it is taking longer than you require – you should probably consider making your grid a VirtuelMode grid (which *is* what I am presuming you mean by “pagination”) – doing so should make your grid presentation relatively instantaneous. See DemoVirtualMode sample app for example.

Hello.
I have a SuperGridControl, where my every single GridCell is an object of my class.
GridColumn newColumn = new GridColumn(columnName);
newColumn.EditorType = typeof(sthClass);
public partial class sthClass : UserControl, IGridCellEditControl

In this class I have a combobox (from DotNetBar).
When I dropdown the combobox and I want to choose last item, I mustn’t choose that because the list of combobox hides, because I move mouse in other GridCell. Is that a way to not selecting a GridCell when mouse move on it?

You may need to configure your edit control’s “CanInterrupt” property (which signifies whether the grid can “interrupt” the current operation of the edit control when the mouse exits the control and enters another cell.

There is no direct support for exporting to Excel. You may, however, be able to leverage the CopySelectedCellsToClipboard function to quickly and easily accomplish your task. If that does not fully provide the support you need, I am sure you have all the rudimentary tools provided in the SuperGrid to permit you to write and accomplish the task you need.

The RightToLeft property is not supported in the SuperGrid, nor is it a supported feature in any of the DNB controls. If you are wanting to right align the data in a given column, row, and/or cell, that is easily accomplished via the appropriate Style settings for those elements.