Mac Developer Library

Developer

AppKit Framework Reference NSTableViewDataSource Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSTableViewDataSource

The NSTableViewDataSource protocol declares the methods that an instance of NSTableView uses to provide the data to a table view and allow editing of the contents of its data source object. More...

Inheritance


Not Applicable

Import Statement


import AppKit @import AppKit;

Availability


Available in OS X v10.6 and later.
  • Returns the number of records managed for aTableView by the data source object.

    Declaration

    Swift

    optional func numberOfRowsInTableView(_ aTableView: NSTableView) -> Int

    Objective-C

    - (NSInteger)numberOfRowsInTableView:(NSTableView *)aTableView

    Parameters

    aTableView

    The table view that sent the message.

    Return Value

    The number of rows in aTableView.

    Discussion

    An instance of NSTableView uses this method to determine how many rows it should create and display. Your numberOfRowsInTableView: implementation is called very frequently, so it must be efficient.

    Both view-based table views and cell-based table views must implement this method.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Called by the table view to return the data object associated with the specified row and column.

    Declaration

    Swift

    optional func tableView(_ aTableView: NSTableView, objectValueForTableColumn aTableColumn: NSTableColumn?, row rowIndex: Int) -> AnyObject?

    Objective-C

    - (id)tableView:(NSTableView *)aTableView objectValueForTableColumn:(NSTableColumn *)aTableColumn row:(NSInteger)rowIndex

    Parameters

    aTableView

    The table view that sent the message.

    aTableColumn

    A column in aTableView.

    rowIndex

    The row of the item in aTableColumn.

    Return Value

    An item in the data source in the specified table column of the view.

    Discussion

    tableView:objectValueForTableColumn:row: is called each time the table cell needs to be redisplayed, so it must be efficient.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Sets the data object for an item in the specified row and column.

    Declaration

    Swift

    optional func tableView(_ aTableView: NSTableView, setObjectValue anObject: AnyObject?, forTableColumn aTableColumn: NSTableColumn?, row rowIndex: Int)

    Objective-C

    - (void)tableView:(NSTableView *)aTableView setObjectValue:(id)anObject forTableColumn:(NSTableColumn *)aTableColumn row:(NSInteger)rowIndex

    Parameters

    aTableView

    The table view that sent the message.

    anObject

    The new value for the item.

    aTableColumn

    A column in aTableView.

    rowIndex

    The row of the item in aTableColumn.

    Discussion

    This method is intended for use with cell-based table views, it must not be used with view-based table views. In view-based tables, use target/action to set each item in the view cell.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Called by aTableView when the mouse button is released over a table view that previously decided to allow a drop.

    Declaration

    Swift

    optional func tableView(_ aTableView: NSTableView, acceptDrop info: NSDraggingInfo, row row: Int, dropOperation operation: NSTableViewDropOperation) -> Bool

    Objective-C

    - (BOOL)tableView:(NSTableView *)aTableView acceptDrop:(id<NSDraggingInfo>)info row:(NSInteger)row dropOperation:(NSTableViewDropOperation)operation

    Parameters

    aTableView

    The table view that sent the message.

    info

    An object that contains more information about this dragging operation.

    row

    The index of the proposed target row.

    operation

    The type of dragging operation.

    Return Value

    YEStrue if the drop operation was successful, otherwise NOfalse.

    Discussion

    The data source should incorporate the data from the dragging pasteboard in the implementation of this method. You can use the draggingPasteboard method to get the data for the drop operation from info.

    To accept a drop on the second row, row would be 2 and operation would be NSTableViewDropOn. To accept a drop below the last row, row would be [aTableView numberOfRows] and operation would be NSTableViewDropAbove.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Returns an array of filenames that represent the indexSet rows for a drag to dropDestination.

    Declaration

    Swift

    optional func tableView(_ aTableView: NSTableView, namesOfPromisedFilesDroppedAtDestination dropDestination: NSURL, forDraggedRowsWithIndexes indexSet: NSIndexSet) -> [AnyObject]

    Objective-C

    - (NSArray *)tableView:(NSTableView *)aTableView namesOfPromisedFilesDroppedAtDestination:(NSURL *)dropDestination forDraggedRowsWithIndexes:(NSIndexSet *)indexSet

    Parameters

    aTableView

    The table view that sent the message.

    dropDestination

    The drop location where the files are created.

    indexSet

    The indexes of the items being dragged.

    Return Value

    An array of filenames (not full paths) for the created files that the receiver promises to create.

    Discussion

    This method is called when a destination has accepted a promise drag.

    For more information on file promise dragging, see documentation on the NSDraggingSource protocol and namesOfPromisedFilesDroppedAtDestination:.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Used by aTableView to determine a valid drop target.

    Declaration

    Swift

    optional func tableView(_ aTableView: NSTableView, validateDrop info: NSDraggingInfo, proposedRow row: Int, proposedDropOperation operation: NSTableViewDropOperation) -> NSDragOperation

    Objective-C

    - (NSDragOperation)tableView:(NSTableView *)aTableView validateDrop:(id<NSDraggingInfo>)info proposedRow:(NSInteger)row proposedDropOperation:(NSTableViewDropOperation)operation

    Parameters

    aTableView

    The table view that sent the message.

    info

    An object that contains more information about this dragging operation.

    row

    The index of the proposed target row.

    operation

    The type of dragging operation proposed.

    Return Value

    The dragging operation the data source will perform.

    Discussion

    The data source may retarget a drop by calling setDropRow:dropOperation: and returning something other than NSDragOperationNone. A data source might retarget for various reasons, such as to provide better visual feedback when inserting into a sorted position.

    To propose a drop on the second row, row would be 2 and operation would be NSTableViewDropOn. To propose a drop below the last row, row would be [aTableView numberOfRows] and operation would be NSTableViewDropAbove.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Returns a Boolean value that indicates whether a drag operation is allowed.

    Declaration

    Swift

    optional func tableView(_ aTableView: NSTableView, writeRowsWithIndexes rowIndexes: NSIndexSet, toPasteboard pboard: NSPasteboard) -> Bool

    Objective-C

    - (BOOL)tableView:(NSTableView *)aTableView writeRowsWithIndexes:(NSIndexSet *)rowIndexes toPasteboard:(NSPasteboard *)pboard

    Parameters

    aTableView

    The table view that sent the message.

    rowIndexes

    An index set of row numbers that will be participating in the drag.

    pboard

    The pasteboard to which to write the drag data.

    Return Value

    YES if the drag operation is allowed, NO otherwise.

    Discussion

    Called by aTableView after it has been determined that a drag should begin, but before the drag has been started.

    To refuse the drag, return NOfalse. To start a drag, return YEStrue and place the drag data onto pboard (data, owner, and so on). The drag image and other drag-related information will be set up and provided by the table view once this call returns with YEStrue.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Implement this method to determine when a dragging session will begin.

    Declaration

    Swift

    optional func tableView(_ tableView: NSTableView, draggingSession session: NSDraggingSession, willBeginAtPoint screenPoint: NSPoint, forRowIndexes rowIndexes: NSIndexSet)

    Objective-C

    - (void)tableView:(NSTableView *)tableView draggingSession:(NSDraggingSession *)session willBeginAtPoint:(NSPoint)screenPoint forRowIndexes:(NSIndexSet *)rowIndexes

    Parameters

    tableView

    The table view.

    session

    The dragging session.

    screenPoint

    The initial drag location in screen coordinates.

    rowIndexes

    The indexes of the rows to be dragged, excluding rows that were not dragged due to tableView:pasteboardWriterForRow: returning nil.

    Discussion

    Implement this method to know when the dragging session is about to begin and to potentially modify the dragging session.

    The dragged item order will directly match the pasteboard writer array used to begin the dragging session with the NSView method beginDraggingSessionWithItems:event:source:. Hence, the order is deterministic, and can be used in tableView:acceptDrop:row:dropOperation: when enumerating the NSDraggingInfo pasteboard classes.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Implement this method to allow the table to update dragging items as they are dragged over a view.

    Declaration

    Swift

    optional func tableView(_ tableView: NSTableView, updateDraggingItemsForDrag draggingInfo: NSDraggingInfo)

    Objective-C

    - (void)tableView:(NSTableView *)tableView updateDraggingItemsForDrag:(id<NSDraggingInfo>)draggingInfo

    Parameters

    tableView

    The table view.

    draggingInfo

    The dragging information.

    Discussion

    Required for multi-image dragging. Typically this will involve invoking enumerateDraggingItemsWithOptions:forView:classes:searchOptions:usingBlock: on the draggingInfo parameter value and setting the draggingItem object’s imageComponentsProvider to a proper image based on the content.

    For view-based table views, you can use the NSTableCellView method draggingImageComponents. For cell-based tables, use the NSCell method draggingImageComponentsWithFrame:inView:.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Implement this method to determine when a dragging session has ended.

    Declaration

    Swift

    optional func tableView(_ tableView: NSTableView, draggingSession session: NSDraggingSession, endedAtPoint screenPoint: NSPoint, operation operation: NSDragOperation)

    Objective-C

    - (void)tableView:(NSTableView *)tableView draggingSession:(NSDraggingSession *)session endedAtPoint:(NSPoint)screenPoint operation:(NSDragOperation)operation

    Parameters

    tableView

    The table view.

    session

    The dragging session.

    screenPoint

    The ending drag location in screen coordinates.

    operation

    The drag operation. See NSDragOperation for supported values.

    Discussion

    This delegate method can be used to determine when the dragging source operation ended at a specific location, such as the trash, by checking for an operation of NSDragOperationDelete.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Called by aTableView to indicate that sorting may need to be done.

    Declaration

    Swift

    optional func tableView(_ aTableView: NSTableView, sortDescriptorsDidChange oldDescriptors: [AnyObject])

    Objective-C

    - (void)tableView:(NSTableView *)aTableView sortDescriptorsDidChange:(NSArray *)oldDescriptors

    Parameters

    aTableView

    The table view that sent the message.

    oldDescriptors

    An array that contains the previous descriptors.

    Discussion

    The data source typically sorts and reloads the data, and adjusts the selections accordingly. If you need to know the current sort descriptors and the data source doesn’t manage them itself, you can get the current sort descriptors by sending aTableView a sortDescriptors message.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

    Available as part of an informal protocol prior to OS X v10.6.