Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/flocked/advancedcollectiontableview
Extended NSCollectionView & NSTableView: Cell- & ItemRegistration, SwiftUI table cells/collection view items,…
https://github.com/flocked/advancedcollectiontableview
appkit cocoa macos nscollectionview nscollectionviewitem nstablecellview nstableview swift swiftui
Last synced: about 2 months ago
JSON representation
Extended NSCollectionView & NSTableView: Cell- & ItemRegistration, SwiftUI table cells/collection view items,…
- Host: GitHub
- URL: https://github.com/flocked/advancedcollectiontableview
- Owner: flocked
- License: mit
- Created: 2022-12-15T15:00:11.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-14T04:39:47.000Z (9 months ago)
- Last Synced: 2024-04-14T14:55:17.309Z (9 months ago)
- Topics: appkit, cocoa, macos, nscollectionview, nscollectionviewitem, nstablecellview, nstableview, swift, swiftui
- Language: Swift
- Homepage:
- Size: 25.7 MB
- Stars: 17
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Advanced NSCollectionView & NSTableView
A framework for NSCollectionView and NSTableView. It provides a collection of classes and extensions, many of them being ports of missing UIKit APIs.
**Take a look at the included sample app which demonstrates most features.**
**For a full documentation take a look at the** [Online Documentation](https://swiftpackageindex.com/flocked/AdvancedCollectionTableView/documentation/).
## NSCollectionView ItemRegistration & NSTableView CellRegistration
A registration for collection view items and table cells that greatly simplifies configurating them. A port of `UICollectionView.CellRegistration`.
```swift
struct GalleryItem {
let title: String
let image: NSImage
}
let tableCellRegistration = NSTableView.CellRegistration {
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
}
}
```
## NSContentConfiguration
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.
### NSHostingConfiguration
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:
```swift
collectionViewItem.contentConfiguration = NSHostingConfiguration {
HStack {
Image(systemName: "star").foregroundStyle(.purple)
Text("Favorites")
Spacer()
}
}
```
### NSListContentConfiguration
A content configuration for a table view cell.
```swift
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
```
### NSItemContentconfiguration
A content configuration for a collection view item.
```swift
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
```
## NSCollectionView Reconfigure Items
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.
```swift
collectionView.reconfigureItems(at: indexPaths)
```
## NSTableView Cell Registration by Class
Apple only allows registering `NSTableCellView` using `NSNib`. This framework lets you register table cell class.
```swift
tableView.register(NSTableCellView.self)
let dequeuedTableCell = tableView.makeView(for: NSTableCellView.self)
```
## NSCollectionView- & NSTableViewDiffableDataSource Item Deletion
Enable deleting items via backspace via `DeletingHandlers`:
```swift
// 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
}
```
## NSDiffableDataSourceSnapshot Apply Options
Apple's `apply(_:animatingDifferences:completion:)` provides two options for applying snapshots to a diffable data source depending on `animatingDifferences`:
- `true` applies a diff of the old and new state and animates updates in the UI.
- `false` is equivalent to calling `reloadData()`. 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.
```swift
diffableDataSource.apply(mySnapshot, .withoutAnimation)
diffableDataSource.apply(mySnapshot, .animated(3.0))
```
## CollectionViewDiffableDataSource
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
## TableViewDiffableDataSource
Simliar to CollectionViewDiffableDataSource.
## Quicklook for NSTableView & NSCollectionView
NSCollectionView/NSTableView `isQuicklookPreviewable` enables quicklook of selected items/cells via spacebar.
There are several ways to provide quicklook previews (see [FZQuicklook](https://github.com/flocked/FZQuicklook) for an extended documentation):
- Diffable collection view & table view datasource with an `ItemIdentifierType` conforming to `QuicklookPreviewable`:
```swift
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() { collectionItem, indexPath, galleryItem in
// configurate …
}
collectionView.dataSource = NSCollectionViewDiffableDataSource(collectionView: collectionView, itemRegistration: ItemRegistration)
collectionView.isQuicklookPreviewable = true
collectionView.quicklookSelectedItems()
```
- `NSCollectionViewItems`s & `NSTableCellView`s `quicklookPreview: QuicklookPreviewable?` property:
```swift
collectionViewItem.quicklookPreview = URL(fileURLWithPath: "someFile.png")
```
## Installation
Add AdvancedCollectionTableView to your app's Package.swift file, or selecting File -> Add Package Dependencies in Xcode:
```swift
.package(url: "https://github.com/flocked/AdvancedCollectionTableView")
```
If you clone the repo, you can run the sample app, which demonstrates most of the API`s.