A framework for NSCollectionView, NSTableView and NSOutlineView. It provides a collection of classes and extensions, many of them being ports of missing UIKit APIs.
Always use the main branch, as else the package might not compile probably.
Take a look at the included sample app which demonstrates most features.
For a full documentation take a look at the Online Documentation.
A registration for collection view items and table cells that greatly simplifies configurating them. A port of UICollectionView.CellRegistration.
struct GalleryItem { let title: String let image: NSImage } let tableCellRegistration = NSTableView.CellRegistration<NSTableCellView, GalleryItem> { tableCell, column, row, galleryItem in tableCell.textField.stringValue = galleryItem.title tableCell.imageView.image = galleryItem.image // Gets called whenever the state of the item changes (e.g. on selection) tableCell.configurationUpdateHandler = { tableCell, state in // Updates the text color based on selection state. tableCell.textField.textColor = state.isSelected ? .controlAccentColor : .labelColor } }
Configurates styling and content for a content view. A port of UIContentConfiguration`.
NSCollectionviewItem, NSTableCellView and NSTableRowView provide contentConfiguration where you can apply them to configurate the content of the item/cell.
A content configuration suitable for hosting a hierarchy of SwiftUI views.
With this configuration you can easily display a SwiftUI view in a collection item and table cell:
collectionViewItem.contentConfiguration = NSHostingConfiguration { HStack { Image(systemName: "star").foregroundStyle(.purple) Text("Favorites") Spacer() } }
A content configuration for a table view cell.
var content = tableCell.defaultContentConfiguration() // Configure content content.text = "Text" content.secondaryText = #"SecondaryText\\nImage displays a system image named "photo""# content.image = NSImage(systemSymbolName: "photo") // Customize appearance content.textProperties.font = .body content.imageProperties.tintColor = .controlAccentColor tableCell.contentConfiguration = content
A content configuration for a collection view item.
public var content = collectionViewItem.defaultContentConfiguration() // Configure content content.text = "Text" content.secondaryText = "SecondaryText" content.image = NSImage(systemSymbolName: "Astronaut Cat") // Customize appearance content.secondaryTextProperties.font = .callout collectionViewItem.contentConfiguration = content
Updates the data for the items without reloading and replacing them. It provides much better performance compared to reloading items. A port of UICollectionView.reconfigureItems.
Any item that has been registered via ItemRegistration, or by class using register(_ itemClass: NSCollectionViewItem.Type), can be recofigurated.
collectionView.reconfigureItems(at: indexPaths)
Apple only allows registering NSTableCellView using NSNib. This framework lets you register table cell class.
tableView.register(NSTableCellView.self) let dequeuedTableCell = tableView.makeView(for: NSTableCellView.self)
Enable deleting items via backspace via DeletingHandlers:
// Allow every item to be deleted dataSource.deletingHandlers.canDelete = { items in return true } // Update the backing store from the final item identifiers dataSource.deletingHandlers.didDelete = { [weak self] items, transaction in guard let self = self else { return } self.backingStore = transaction.finalSnapshot.itemIdentifiers }
Apple's apply(_:animatingDifferences:completion:) provides two options for applying snapshots to a diffable data source depending on animatingDifferences:
trueapplies a diff of the old and new state and animates updates in the UI.falseis equivalent to callingreloadData(). It reloads every item.
NSDiffableDataSourceSnapshotApplyOption lets you perform a diff even without animations for much better performance compared to using Apple's reloadData().
It also provides additional options:
- usingReloadData: All items get reloaded.
- animated(withDuration: CGFloat): Changes get applied animated.
- nonAnimated: Changes get applied immediatly.
diffableDataSource.apply(mySnapshot, .withoutAnimation) diffableDataSource.apply(mySnapshot, .animated(3.0))
An extended `NSCollectionViewDiffableDataSource that provides:
- Reordering items by dragging them via
reorderingHandlers - Deleting items via backspace via
deletingHandlers - Quicklook previews of items via spacebar by providing items conforming to
QuicklookPreviewable - Right click menu provider for selected items
It includes handlers for:
- Prefetching items
- Selecting items
- Highlighting items
- Displaying items
- Hovering items with the mouse.
- Pinching of the collection view
Simliar to CollectionViewDiffableDataSource.
A diffable data source for NSOutlineView.
Example usage of a data source with a String as ItemIdentifierType:
let dataSource = OutlineViewDiffableDataSource<String>(outlineView: outlineView, cellRegistration: cellRegistration) var snapshot = OutlineViewDiffableDataSourceSnapshot<String>() let rootItems ["Root 1", "Root 2", "Root 3", "Root 4", "Root 5"] snapshot.append(rootItems) rootItems.forEach { rootItem in let childItems = (1...5).map { "\(rootItem).\(0ドル)" } snapshot.append(childItems, to: rootItem) childItems.forEach { childItem in let grandchildItems = (1...5).map { "\(childItem).\(0ドル)" } snapshot.append(grandchildItems, to: childItem) } } dataSource.apply(snapshot)
NSCollectionView/NSTableView isQuicklookPreviewable enables quicklook of selected items/cells via spacebar.
There are several ways to provide quicklook previews (see FZQuicklook for an extended documentation):
- Diffable collection view & table view datasource with an
ItemIdentifierTypeconforming toQuicklookPreviewable:
struct GalleryItem: QuicklookPreviewable { let title: String let imageURL: URL // The file url for the quicklook preview. let previewItemURL: URL? { return imageURL } // The quicklook preview title displayed on the top of the Quicklook panel. let previewItemTitle: String? { return title } } let itemRegistration = NSCollectionView.ItemRegistration<NSCollectionViewItem, GalleryItem>() { collectionItem, indexPath, galleryItem in // configurate ... } collectionView.dataSource = NSCollectionViewDiffableDataSource<Section, GalleryItem>(collectionView: collectionView, itemRegistration: ItemRegistration) collectionView.isQuicklookPreviewable = true collectionView.quicklookSelectedItems()
NSCollectionViewItemss &NSTableCellViewsquicklookPreview: QuicklookPreviewable?property:
collectionViewItem.quicklookPreview = URL(fileURLWithPath: "someFile.png")
Add AdvancedCollectionTableView to your app's Package.swift file, or selecting `File -> Add Package Dependencies in Xcode:
.package(url: "https://github.com/flocked/AdvancedCollectionTableView",)
Always use the main branch, as else the code might not compile probably.
If you clone the repo, you can run the sample app, which demonstrates most of the API`s.
OutlineViewDiffableDataSource: Dragging rows isn't working.- All diffable datasources: Some inconsistency for dropping content and dragging out rows/items.