Inherits from UIScrollView
Conforms to UIScrollViewDelegate
Declared in SGrid.h
Availability
Related samples

Overview

The ShinobiGrid class is intended for easy construction of a grid structure that is presented in columns, rows and sections, composed of cells, separated by gridlines, that display content to the user. Columns, rows and sections are zero-indexed, where the first column in a grid is at index 0, the first row in a section is at index 0 and the first section in the grid is at index 0. Cells can be located within a grid from their grid coordinate.

Sections group rows horizontally and have section headers that allow the user to tap and collapse a section. The grid will have one section by default, but this can be altered by implementing the appropriate SGridDelegate method.

A ShinobiGrid object can present content that is too large for its own frame by allowing for panning and scrolling. This behaviour is automatic where the content dimensions (total cell heights or widths) are greater than the grid’s dimensions - no additional setup/calibration is required. The grid will calculate the height of columns and width of rows if none are supplied - in order to stop this behaviour simply implement the appropriate style method from SGridDelegate or apply the appropriate default style on the grid itself (such as defaultRowStyle etc.).

A ShinobiGrid object must have an associated object that acts as the data source (which must conform to the SGridDataSource protocol). The data source provides the necessary information to construct the grid, such as number of rows, sections and columns, and the content to be displayed within each cell. The data source concerns itself solely with the data model, and issues relating to the style of the grid are controlled through the delegate.

Warning: Important The datasource property is a weak reference to the grid’s datasource. This means you must maintain a reference to it, to prevent prevent the datasource from being autoreleased / released by ARC.

The delegate of the ShinobiGrid object must conform to the SGridDelegate protocol and can be used to provide styles for specific rows/columns/gridlines. Only provide a delegate for your ShinobiGrid object if you wish to provide a style for a specific element of the grid. If you wish to style the grid in a uniform manner (every gridline will be styled identically etc) then the properties such as defaultRowStyle, defaultColumnStyles and defaultGridLineStyle are designed for this purpose. As such it is not necessary for a ShinobiGrid to have a delegate.

Warning: Important The delegate property is a weak reference to the grid’s delegate. This means you must maintain a reference to it, to prevent prevent the delegate from being autoreleased / released by ARC.

ShinobiGrid uses cell pooling to make your grid as memory efficient as possible. Cells that are not currently visible are returned to an internal cell pool for later use and cells that become visible due to users scrolling/panning are retrieved from this pool. This means that ShinobiGrid caches cells only for visible rows and columns, but caches styling objects for the entire grid. For ShinobiGrid to be able to pool cells correctly it needs to know what the cells will be used for - this is where the dequeueReusableCellWithIdentifier: method is utilised. You should use a different reuseIdentifier for each distinct type of cell within your grid - for example if you have header cells and normal cells in your grid, you might use the identifiers "HEADER" and "NORMAL". For code examples of using the identifiers see the ShinobiGrid sample apps.

Warning: Important The allocation/instantiation of cells must be done via the dequeueReusableCellWithIdentifier: method.

Tasks

Changing a ShinobiGrid's Default Styles

  •   defaultGridLineStyle

    This property is the default style that will be applied to all gridlines that belong this this ShinobiGrid object.

    property
  •   defaultBorderStyle

    This property represents the style that will be applied to this grid’s content border.

    property
  •   defaultSectionHeaderStyle

    This property represents the style that will be applied to all section headers in this grid.

    property
  •   defaultRowStyle

    This property sets a default row style that will be used in all rows in all sections in this grid. Use this property to quickly set a base row style for the grid.

    property
  •   defaultSelectedCellStyle

    The default style to be used upon row/cell selection.

    property
  •   defaultColumnStyle

    This property sets a default column style that will be used in all columns in this grid. Use this property to quickly set a base column style for the grid.

    property
  •   minimumRowHeight

    If the grid cannot find a row height to use then it will try to calculate one to use. It does this by trying to fit every row into the height of the grid - this property dictates the minimum row height that will be used in this case.

    property
  •   minimumColWidth

    If the grid cannot find a column width to use then it will try to calculate one to use. It does this by trying to fit every column into the width of the grid - this property dictates the minimum column width that will be used in this case and also applies to resizing columns via a pinch gesture.

    property
  •   enableBlending

    Indicates whether the grid will alpha blend the style colors.

    property
  •   defaultArrowImage

    The default arrow image that will be used when indicating the directions that a column/row can be dragged in after initating a long-press gesture.

    property

Configuring a ShinobiGrid

  • – dequeueReusableCellWithIdentifier:

    Returns a reusable ShinobiGrid cell object located by its identifier.

  •   rowStylesTakePriority

    This boolean value dictates the course of action to take if conflicting row and column styles are found. If set to YES, then the row style will take priority over the column style. If set to NO then the oppostie is true. The default value is NO (column styles take priority by default).

    property
  •   linesOnTop

    Controls the manner in which the gridlines are displayed in this grid.

    property
  • – freezeColsToTheLeftOfAndIncludingIndex:

    This method freezes all columns to the left of (and including) the column at index colIndex. Note that if a cell belongs to both a frozen row and frozen column that it will not be scrollable in any direction.

  • – freezeRowsAboveAndIncludingRow:

    This method freezes all rows above (and including) the supplied row. Note that if a cell belongs to both a frozen row and frozen column that it will not be scrollable in any direction.

  •   numberOfFrozenColumns

    Property states how many columns should be frozen. The columns are frozen from the left hand side of the grid. The default value is 0, which represents there being no frozen columns.

    property
  •   numberOfFrozenRows

    Property states how many rows should be frozen. The rows are frozen from the top of the grid downwards. The default value is 0, which represents there being no frozen rows.

    property
  •   defaultFrozenColumnShadowColor

    Property controls the color of drop shadow that appears for a frozen column. The default value is [UIColor blackColor].

    property
  •   defaultFrozenRowShadowColor

    Property controls the color of drop shadow that appears for a frozen row. The default value is [UIColor blackColor].

    property
  •   canResizeColumnsViaPinch

    Dictates whether this grid’s columns can be resized or not.

    property

Selection of Cells

Accessing Cells and Cell Visibility

  • – visibleCellAtCol:andRow:

    Returns the cell that belongs to colIndex and row. Use this to retrieve a cell at a given coordinate.

  • – visibleColumnIndexes

    Returns an NSArray of NSNumber objects. Each NSNumber object represents a currently visible colIndex. Use this function to query which columns are currently visible in the grid.

  • – visibleRows

    Returns an NSArray of NSValue objects. Each NSValue object represents a currently visible row - the SGridRow struct can be retrieved from an NSValue object by first providing a struct variable such as SGridRow visibleRow, and then using the getValue: method of the NSValue object like so - [rowValueObject getValue:&visibleRow]. Use this function to query which rows are currently visible within the grid.

  • – findRowAfterRow:

    This function will return the next row down.

  • – findRowBeforeRow:

    This function will return the next row up.

Dragging and Dropping Columns and Rows

  •   canReorderRowsViaLongPress

    A boolean that dictates whether the rows of this grid can be dragged and dropped by the user.

    property
  •   canReorderColsViaLongPress

    A boolean that dictates whether the columns of this grid can be dragged and dropped by the user.

    property
  •   defaultPermittedDragDirection

    An enum that dictates whether the rows of this grid can be dragged and dropped by the user.

    property
  •   tintColor

    The color to use when tinting the grid, during a drag and drop operation. Defaults to nil, for no tint color.

    property

Gesture Event Handling

Reloading and Redrawing the ShinobiGrid

Managing the Delegate and Data Source

  •   dataSource

    The object that acts as the data source for the receving ShinobiGrid object.

    property
  •   delegate

    The object that acts as the delegate of the receiving ShinobiGrid object.

    property
  •   licenseKey

    This property is now deprecated. You should use the licenseKey property on the ShinobiGrids class instead.

    property

Grid Version

  • + getInfo

    DEPRECATED in 2.7.0 - You should use [ShinobiGrids getInfo] instead.

  • – getInfo

    DEPRECATED in 2.7.0 - You should use [ShinobiGrids getInfo] instead.

Properties

canEditCellsViaDoubleTap

Dictates whether this grid can be edited or not.

@property (nonatomic, assign) BOOL canEditCellsViaDoubleTap

Discussion

If canEditCellsViaDoubleTap is YES, then a user can double tap a cell to edit its contents. Default value is NO.

See the shinobiGrid:didFinishEditingCell: method of the SGridDelegate protocol for a means of intercepting user’s changes to cell content.

Having this value set to YES means that the grid has an internal double tap gesture recogniser that is enabled. Setting this property to NO disables this gesture recogniser.

Warning: Important: This method has been deprecated in preference of doubleTapEventMask.

Declared In

SGrid.h

canReorderColsViaLongPress

A boolean that dictates whether the columns of this grid can be dragged and dropped by the user.

@property (nonatomic, assign) BOOL canReorderColsViaLongPress

Discussion

If set to YES then the user can touch and hold a cell to initiate the drag and drop of a column.

ShinobiGrid has an internal long press gesture recogniser which is enabled if either this property or the canReorderRowsViaLongPress property is set to YES. Setting both these properties to NO disables this gesture recogniser.

Warning: Important: This method has been deprecated in preference of defaultPermittedDragDirection.

Declared In

SGrid.h

canReorderRowsViaLongPress

A boolean that dictates whether the rows of this grid can be dragged and dropped by the user.

@property (nonatomic, assign) BOOL canReorderRowsViaLongPress

Discussion

If set to YES then the user can touch and hold a cell to initiate the drag and drop of a row.

ShinobiGrid has an internal long press gesture recogniser which is enabled if either this property or the canReorderColsViaLongPress property is set to YES. Setting both these properties to NO disables this gesture recogniser.

Warning: Important: This method has been deprecated in preference of defaultPermittedDragDirection.

Declared In

SGrid.h

canResizeColumnsViaPinch

Dictates whether this grid’s columns can be resized or not.

@property (nonatomic, assign) BOOL canResizeColumnsViaPinch

Discussion

If canResizeColumnsViaPinch is YES, then a user can pinch two columns to resize them. Default value is NO.

Warning: Important Having this value set to YES means that the grid has an internal pinch gesture recogniser that is enabled. Setting this property to NO disables this gesture recogniser.

Declared In

SGrid.h

canSelectViaSingleTap

Dictates whether this grid can be single tapped or not.

@property (nonatomic, assign) BOOL canSelectViaSingleTap

Discussion

If canSelectViaSingleTap is YES, then a user can single tap grid cells and section headers. Tapping a cell triggers the shinobiGrid:willSelectCellAtCoord: delegate call. Tapping a section header collapses the section. Default value for this property is YES.

Having this value set to YES means that the grid has an internal single tap gesture recogniser that is enabled. Setting this property to NO disables this gesture recogniser.

Warning: Important: This method has been deprecated in preference of singleTapEventMask.

Declared In

SGrid.h

dataSource

The object that acts as the data source for the receving ShinobiGrid object.

@property (nonatomic, assign) id<SGridDataSource> dataSource

Discussion

The data source must adopt the SGridDataSource protocol.

Warning: Important The datasource property is a weak reference to the grid’s datasource. This means you must maintain a reference to it, to prevent prevent the datasource from being autoreleased / released by ARC.

Declared In

SGrid.h

defaultArrowImage

The default arrow image that will be used when indicating the directions that a column/row can be dragged in after initating a long-press gesture.

@property (nonatomic, retain) UIImage *defaultArrowImage

Discussion

Warning: Important The arrow supplied should point right. The top, left and bottom arrow images will be supplied by rotating this image as though it were pointing right initially.

Declared In

SGrid.h

defaultBorderStyle

This property represents the style that will be applied to this grid’s content border.

@property (nonatomic, retain) SGridBorderStyle *defaultBorderStyle

Discussion

The border belongs the the content of the grid and not the grid itself. If you wish to apply a border to the grid then this can be accomplished as with a regular UIView through the use of the layer property (as ShinobiGrid is a descendant of UIView).

Declared In

SGrid.h

defaultColumnStyle

This property sets a default column style that will be used in all columns in this grid. Use this property to quickly set a base column style for the grid.

@property (nonatomic, retain) SGridColRowStyle *defaultColumnStyle

Discussion

This property will be overriden by any style that is more specific, such as styles assigned in the delegate methods or styles assigned when returning a cell in the datasource method.

Declared In

SGrid.h

defaultFrozenColumnShadowColor

Property controls the color of drop shadow that appears for a frozen column. The default value is [UIColor blackColor].

@property (nonatomic, retain) UIColor *defaultFrozenColumnShadowColor

Declared In

SGrid.h

defaultFrozenRowShadowColor

Property controls the color of drop shadow that appears for a frozen row. The default value is [UIColor blackColor].

@property (nonatomic, retain) UIColor *defaultFrozenRowShadowColor

Declared In

SGrid.h

defaultGridLineStyle

This property is the default style that will be applied to all gridlines that belong this this ShinobiGrid object.

@property (nonatomic, retain) SGridLineStyle *defaultGridLineStyle

Discussion

Any style applied to a gridline via the delegate object will take priority over this property.

Declared In

SGrid.h

defaultPermittedDragDirection

An enum that dictates whether the rows of this grid can be dragged and dropped by the user.

@property (nonatomic, assign) SGridDragDirection defaultPermittedDragDirection

Discussion

If set to SGridDragDirectionBoth then the user can touch and hold a cell to initiate the drag and drop of a row.

If set to SGridDragDirectionCol, only columns can be dragged. If set to SGridDragDirectionRow, only rows can be dragged. If set to SGridDragDirectionNone, nothing can be dragged.

Warning: Important ShinobiGrid has an internal long press gesture recogniser which is enabled if either this property is not SGridDragDirectionNone. Setting this property to SGridDragDirectionNone disables this gesture recogniser.

Declared In

SGrid.h

defaultRowStyle

This property sets a default row style that will be used in all rows in all sections in this grid. Use this property to quickly set a base row style for the grid.

@property (nonatomic, retain) SGridColRowStyle *defaultRowStyle

Discussion

This property will be overriden by any style that is more specific, such as styles assigned in the delegate methods or styles assigned when returning a cell in the datasource method.

Declared In

SGrid.h

defaultSectionHeaderStyle

This property represents the style that will be applied to all section headers in this grid.

@property (nonatomic, retain) SGridSectionHeaderStyle *defaultSectionHeaderStyle

Discussion

To specify individual styles for each (or a particular) section header then see the shinobiGrid:headerStyleForSectionAtIndex: method of SGridDelegate. Note that a style specified with the delegate method will take priority over this property.

Declared In

SGrid.h

defaultSelectedCellStyle

The default style to be used upon row/cell selection.

@property (nonatomic, retain) SGridCellStyle *defaultSelectedCellStyle

Declared In

SGrid.h

deferredLayout

Controls whether or not your app should wait for the grid to finish laying out before appearing. If set to YES the layout of the grid will be pushed to the beginning of your app’s next run loop - the effect of this is that your app will appear without the grid and the grid will add itself to the view when it has finished laying out. Default value is NO.

@property (nonatomic, assign) BOOL deferredLayout

Declared In

SGrid.h

delegate

The object that acts as the delegate of the receiving ShinobiGrid object.

@property (nonatomic, assign) id<SGridDelegate> delegate

Discussion

The delegate must adopt the SGridDelegate protocol. The delegate is not retained.

Warning: Important The delegate property is a weak reference to the grid’s delegate. This means you must maintain a reference to it, to prevent prevent the delegate from being autoreleased / released by ARC.

Declared In

SGrid.h

directionalLockAllowDiagonalPanning

A Boolean value that determines whether directional lock disallows diagnonal panning.

@property (nonatomic, assign) BOOL directionalLockAllowDiagonalPanning

Discussion

This property only takes effect if directionalLockEnabled is YES.

If this property is NO, scrolling behaves as dictated by directionalLockEnabled.

If this property is YES and the user begins dragging, the scroll view disables scrolling in the other direction. If the drag direction is diagonal, then the grid will lock in the most dominant direction.

The default value is NO.

Declared In

SGrid.h

doubleTapEventMask

The type of event that the grid fires upon a double tap

@property (nonatomic) SGridEvent doubleTapEventMask

Discussion

See singleTapEventMask

To disable the double tap gesture, set this property to SGridEventNone

Default SGridEventEdit

Declared In

SGrid.h

enableBlending

Indicates whether the grid will alpha blend the style colors.

@property (nonatomic, assign) BOOL enableBlending

Discussion

An example of where color layering occurs is when you have a defaultRowStyle that has a red background color and a column style that has a blue background color. If the blue background color had an alpha of 1 then no blending will take place, but an alpha of less than 1 blends so that we see the red color ‘beneath’ the blue color. If this property is NO then, then the color that is ‘on top’ in the layering will be used without blending with the ‘beneath’ colors (in the example above we would see a blue background color).

Declared In

SGrid.h

licenseKey

This property is now deprecated. You should use the licenseKey property on the ShinobiGrids class instead.

@property (nonatomic, retain) NSString *licenseKey

Discussion

The License Key for this Grid

A valid license key must be set before the grid will render

Declared In

SGrid.h

linesOnTop

Controls the manner in which the gridlines are displayed in this grid.

@property (nonatomic, assign) SGridLinesOnTop linesOnTop

Discussion

If this property is set to SGridLinesVerticalOnTop then the vertical gridlines will be drawn over the top of the horizontal gridlines. The opposite is true if this property is set to SGridLinesHorizontalOnTop.

Declared In

SGrid.h

minimumColWidth

If the grid cannot find a column width to use then it will try to calculate one to use. It does this by trying to fit every column into the width of the grid - this property dictates the minimum column width that will be used in this case and also applies to resizing columns via a pinch gesture.

@property (nonatomic, retain) NSNumber *minimumColWidth

Discussion

Warning: Important: This method has been deprecated in preference of defaultColumnStyle.minimumSize.

Declared In

SGrid.h

minimumRowHeight

If the grid cannot find a row height to use then it will try to calculate one to use. It does this by trying to fit every row into the height of the grid - this property dictates the minimum row height that will be used in this case.

@property (nonatomic, retain) NSNumber *minimumRowHeight

Discussion

Warning: Important: This method has been deprecated in preference of defaultRowStyle.minimumSize.

Declared In

SGrid.h

numberOfFrozenColumns

Property states how many columns should be frozen. The columns are frozen from the left hand side of the grid. The default value is 0, which represents there being no frozen columns.

@property (nonatomic, assign) NSUInteger numberOfFrozenColumns

Declared In

SGrid.h

numberOfFrozenRows

Property states how many rows should be frozen. The rows are frozen from the top of the grid downwards. The default value is 0, which represents there being no frozen rows.

@property (nonatomic, assign) NSUInteger numberOfFrozenRows

Declared In

SGrid.h

preventSingleRowDeselection

Prevents single-row deselection. When the grid is in single-row selection mode, this will prevent the user from deselecting the selected row. Defaults to NO.

@property (nonatomic, assign) BOOL preventSingleRowDeselection

Declared In

SGrid.h

rowStylesTakePriority

This boolean value dictates the course of action to take if conflicting row and column styles are found. If set to YES, then the row style will take priority over the column style. If set to NO then the oppostie is true. The default value is NO (column styles take priority by default).

@property (nonatomic, assign) BOOL rowStylesTakePriority

Discussion

If you set the row at index 0 to have a backgroundColor of red, and the column at index 0 to have a backgroundColor of blue, then the cell at gridCoord {0,0} is being told to have a backgroundColor of red and blue. Setting this property to YES in this instance would mean that the row style (red background) will be appled.

Declared In

SGrid.h

selectionMode

Controls the cell selection mode of the grid.

@property (nonatomic, assign) SGridSelectionMode selectionMode

Discussion

SGridSelectionModeCellSingle means that by default the user can only select one cell at a time through gestures. When selecting a cell in this mode an attempt to deselect all currently selected cells will be made. SGridSelectionModeCellMulti means that by default the user can select multiple cells through gestures (no attempt to deselect currently selected cells will be made). SGridSelectionModeRowSingle means that by default the user can only select one row at a time through gestures. When selecting a row in this mode an attempt to deselect all currently selected cells will be made. SGridSelectionModeRowMulti means that by default the user can select multiple rows through gestures (no attempt to deselect currently selected cells will be made). SGridSelectionModeNone means that no selection will take place as a result of a recognised gesture.

Declared In

SGrid.h

singleTapEventMask

The type of event that the grid fires upon a single tap

@property (nonatomic) SGridEvent singleTapEventMask

Discussion

typedef enum {
SGridEventNone = 0,
SGridEventSelect = 1 << 0,
SGridEventEdit = 1 << 1,
} SGridEvent;

SGridEvent is a bitmask, allowing you to specify multiple events for a single gesture. For example, singleTapEventMask = SGridEventSelect | SGridEventEdit will cause the grid to select and edit a cell on single tap.

The grid may be configured to use either select or edit a cell on a single tap. To disable the single tap gesture, set this property to SGridEventNone

Default SGridEventSelect

Declared In

SGrid.h

tintColor

The color to use when tinting the grid, during a drag and drop operation. Defaults to nil, for no tint color.

@property (nonatomic, retain) UIColor *tintColor

Declared In

SGrid.h

Class Methods

getInfo

DEPRECATED in 2.7.0 - You should use [ShinobiGrids getInfo] instead.

+ (NSString *)getInfo

Discussion

Warning: DEPRECATED in 2.7.0 - You should use [ShinobiGrids getInfo] instead.

Declared In

SGrid.h

Instance Methods

clearAllSelectedCellsWithAnimation:

Set all the currently selected cells to deselect.

- (void)clearAllSelectedCellsWithAnimation:(BOOL)animate

Parameters

animate

A boolean that controls if the clearing of the selected cells should be animated or not.

Declared In

SGrid.h

dequeueReusableCellWithIdentifier:

Returns a reusable ShinobiGrid cell object located by its identifier.

- (id)dequeueReusableCellWithIdentifier:(NSString *)identifier

Declared In

SGrid.h

findRowAfterRow:

This function will return the next row down.

- (SGridRow)findRowAfterRow:(SGridRow)rowToStepDownFrom

Parameters

rowToStepDownFrom

The row that will be stepped down from in order to find the next row.

Return Value

The row resulting from incrementing rowToStepDownFrom by one place.

Discussion

Warning: Important This function is purely a utility function and has no bounds checking in relation to the grid. If you ask it to return the next row down from the very last row in the grid, it will return what would be the next row down regardless of the fact that the returned row does not exist in the grid.

Declared In

SGrid.h

findRowBeforeRow:

This function will return the next row up.

- (SGridRow)findRowBeforeRow:(SGridRow)rowToStepUpFrom

Parameters

rowToStepUpFrom

The row that will be stepped up from in order to find the previous row.

Return Value

The row resulting from decrementing rowToStepUpFrom by one place.

Discussion

Warning: Important This function is purely a utility function and has no bounds checking in relation to the grid. If you ask it to return the next row up from the very first row in the grid, it will return what would be the next row up regardless of the fact that the returned row does not exist in the grid.

Declared In

SGrid.h

freezeColsToTheLeftOfAndIncludingIndex:

This method freezes all columns to the left of (and including) the column at index colIndex. Note that if a cell belongs to both a frozen row and frozen column that it will not be scrollable in any direction.

- (void)freezeColsToTheLeftOfAndIncludingIndex:(NSInteger)colIndex

Parameters

colIndex

The index of the column that should be frozen, along with all columns that have a column index less than colIndex.

Discussion

Warning: Important: This method has been deprecated in preference of the numberOfFrozenCols property.

Declared In

SGrid.h

freezeRowsAboveAndIncludingRow:

This method freezes all rows above (and including) the supplied row. Note that if a cell belongs to both a frozen row and frozen column that it will not be scrollable in any direction.

- (void)freezeRowsAboveAndIncludingRow:(SGridRow)row

Parameters

row

The row that should be frozen, along with all rows that appear above it in the grid.

Discussion

Warning: Important: This method has been deprecated in preference of the numberOfFrozenRows property.

Declared In

SGrid.h

getInfo

DEPRECATED in 2.7.0 - You should use [ShinobiGrids getInfo] instead.

- (NSString *)getInfo

Discussion

Warning: DEPRECATED in 2.7.0 - You should use [ShinobiGrids getInfo] instead.

Declared In

SGrid.h

numberOfColumns

Returns the total number of columns that the grid currently has.

- (NSUInteger)numberOfColumns

Return Value

NSUInteger that represents the number of columns for this grid.

Declared In

SGrid.h

numberOfRowsForSection:

Returns the total number of rows that the grid currently has in a particular section. Returns NSNotFound if sectionIndex does not exist in the grid.

- (NSUInteger)numberOfRowsForSection:(NSInteger)sectionIndex

Parameters

sectionIndex

The index of the section for which you are requesting the number of rows.

Return Value

NSUInteger that represents the number of rows for the section at sectionIndex for this grid.

Declared In

SGrid.h

numberOfSections

Returns the number of sections that the grid currently has.

- (NSUInteger)numberOfSections

Return Value

NSUInteger that represents the number of sections for this grid.

Declared In

SGrid.h

redrawColsAtIndices:

Redraws the specified columns.

- (void)redrawColsAtIndices:(NSArray *)colIndices

Parameters

columns

An array of NSNumber objects that represent the indices of the columns to be redrawn. The method intValue will be used to extract the index from each NSNumber object.

Discussion

This causes the columns in question to have their styles rebuilt and reapplied (according to the grid’s style heirarchy rules). This includes querying any delegate methods responsible for style. This method does not query the grid’s data source.

Warning: Important This does not update column widths or query number of rows, sections or columns. If you wish to update dimensions of the grid you must use reload.

Declared In

SGrid.h

redrawRows:

Redraws the specified rows.

- (void)redrawRows:(NSArray *)rows

Parameters

rows

An array of NSValue objects that contain SGridRow structs representing the rows to be redrawn.

Discussion

This causes the rows in question to have their styles rebuilt and reapplied (according to the grid’s style heirarchy rules). This includes querying any delegate methods responsible for style. This method does not query the grid’s data source.

Warning: Important This does not update row heights or query number of rows, sections or columns. If you wish to update dimensions of the grid you must use reload.

Declared In

SGrid.h

reload

Reloads this ShinobiDataGrid object.

- (void)reload

Discussion

This method reloads the grid by clearing all state and querying all data source and delegate methods.

Warning: Important This is the only method from the Reload and Redraw variety that forces a recheck of column widths and row heights and is therefore the most expensive of these methods due to the need to reposition all grid elements.

Declared In

SGrid.h

reloadColsAtIndices:

Reloads the data for the columns at the specified indices.

- (void)reloadColsAtIndices:(NSArray *)colIndices

Parameters

columns

An array of SDataGridColumn objects representing the columns to be redrawn.

Discussion

This forces a query of your data source for all visible rows in the columns at the supplied indices. This method also triggers a redraw of the specified columns as per redrawColumns:

Warning: Important This does not update column widths or query number of rows, sections or columns. If you wish to update dimensions of the grid you must use reload.

Declared In

SGrid.h

reloadRows:

Reloads the data for the specified rows.

- (void)reloadRows:(NSArray *)rows

Parameters

rows

An array of NSValue objects that contain SGridRow structs representing the rows to be redrawn.

Discussion

This forces a query of your data source for all visible columns in the supplied rows. This method also triggers a redraw of the specified rows as per redrawRows:

Warning: Important This does not update row heights or query number of rows, sections or columns. If you wish to update dimensions of the grid you must use reload.

Declared In

SGrid.h

sectionAtIndexIsCollapsed:

Returns whether or not a section in this ShinobiGrid is currently collapsed.

- (BOOL)sectionAtIndexIsCollapsed:(NSUInteger)index

Parameters

index

The index of the section to be checked for collapse.

Return Value

A bool that indicates whether the section at index is collapsed. YES if collapsed state. NO if expanded state.

Declared In

SGrid.h

selectedCellGridCoords

Return an array of grid coordinates of all the currently selected (and visible) cells.

- (NSArray *)selectedCellGridCoords

Return Value

NSArray of SGridCoord objects that locate all the selected, visible cells in the grid.

Discussion

If no cells are currently selected then returns an empty array. Grid coordinates representing cells that are not visible are not returned.

Declared In

SGrid.h

selectedRows

Return an array of NSValue objects that represent the currently selected rows in the grid.

- (NSArray *)selectedRows

Return Value

NSArray of NSValue objects that encode SGridRow structs indicating the currently selected rows.

Declared In

SGrid.h

setRow:asSelected:animated:

Set an entire row in this grid as being selected/deselected.

- (void)setRow:(SGridRow)row asSelected:(BOOL)isSelected animated:(BOOL)animated

Parameters

row

The row to set as selected/deselected.

isSelected

YES if the row should be set as selected.

animated

YES if this row’s selection change should be animated.

Discussion

Using this method results in the will/did select/deselect delegate callback methods being called. The should delegate callbacks will not be called.

Warning: Important Using this method ignores the selectionMode property, meaning that no automatic cell/row deselection will occur.

Declared In

SGrid.h

setSectionAtIndex:asCollapsed:

Sets a given section of this ShinobiGrid as collapsed or expanded.

- (void)setSectionAtIndex:(NSUInteger)index asCollapsed:(BOOL)collapsed

Parameters

index

The index of the section that is to be collapsed/expanded.

collapsed

A bool that indicates what the section should be set to - YES collapses the section and NO expands the section.

Discussion

Setting an already expanded section to expand (or a collapsed section to collapse) has no effect.

Declared In

SGrid.h

setSelectedRows:

Calls setSelectedRows:animated: with animated == NO.

- (void)setSelectedRows:(NSArray *)newSelectedRows

Declared In

SGrid.h

setSelectedRows:animated:

Replaces the currently selected rows with a new NSArray of selected rows.

- (void)setSelectedRows:(NSArray *)newSelectedRows animated:(BOOL)animated

Parameters

newSelectedRows

An NSArray of NSValue objects (that contain SGridRow structs) to be marked as selected.

animated

YES if the clear of old selected rows and the selection of the new rows should be animated.

Discussion

This results in all the currently selected rows being deselected, and then all the rows in newSelectedRows being set as selected by calling setRow:asSelected:animated: on all of them.

Declared In

SGrid.h

visibleCellAtCol:andRow:

Returns the cell that belongs to colIndex and row. Use this to retrieve a cell at a given coordinate.

- (SGridCell *)visibleCellAtCol:(NSInteger)colIndex andRow:(SGridRow)row

Parameters

colIndex

The index of the column that the cell should belong to.

row

The row that the cell should belong to.

Return Value

An object representing the cell at grid coordinate {colIndex, row}.

Discussion

Warning: Important Note that this method will only retrieve cells that are currently visible in the grid. If an attempt is made to retrieve a cell that is outside the bounds of the grid, nil will be returned.

Declared In

SGrid.h

visibleColumnIndexes

Returns an NSArray of NSNumber objects. Each NSNumber object represents a currently visible colIndex. Use this function to query which columns are currently visible in the grid.

- (NSArray *)visibleColumnIndexes

Declared In

SGrid.h

visibleRows

Returns an NSArray of NSValue objects. Each NSValue object represents a currently visible row - the SGridRow struct can be retrieved from an NSValue object by first providing a struct variable such as SGridRow visibleRow, and then using the getValue: method of the NSValue object like so - [rowValueObject getValue:&visibleRow]. Use this function to query which rows are currently visible within the grid.

- (NSArray *)visibleRows

Declared In

SGrid.h