dir_picker 0.8.0
dir_picker: ^0.8.0 copied to clipboard
A Flutter plugin for picking directories and listing file system entries, supporting Android, iOS, macOS, Windows, Linux, and Web via FFI and JNI.
0.8.0 #
- Breaking: platform failures now throw
DirPickerException, with the code incodeand the platform's text inmessage, instead ofException('CODE: message'). Comparee.codewith the constants on the class, such asDirPickerException.alreadyActive. It implementsException, soon Exceptionhandlers still catch it, and itstoString()is nowDirPickerException(CODE): message(#60) - Breaking: Linux/Windows:
listEntries/streamEntriesthrowDirPickerExceptionwithLIST_ERRORwhen the picked directory can't be read, instead of aFileSystemException, as the other platforms do (#60) - Breaking: Web: errors from the browser are reported as
DirPickerException:PICKER_ERRORfrompick()(other than cancelling, which still returnsnull) andLIST_ERRORfromlistEntries/streamEntries. Before, theDOMExceptionwas rethrown (#60) - Android: deprecate
PickOptions.android(shouldPersist:)andAndroidOptions. CallDirPicker.persist(location)afterpick()instead: it takes the same permission and returns the token forrestore. Both will be removed in 1.0.0 (#61) - Web:
DirPicker.persist,restore,releaseandpersistedTokensnow work, keeping the folder's handle in IndexedDB. They used to throwUnsupportedError(persistedTokensreturned an empty list) (#62) - Web:
WebPickedLocation.hasAccess()andrequestAccess()check and ask for permission to a restored folder; callrequestAccess()from a click (#62)
0.7.0 #
- Android: add
DirPicker.persistedTokens(), which lists the folder permissions the system keeps for the app, so it canreleasethe ones it no longer has a token for and stay under Android's per-app limit. Other platforms keep no such permissions and return an empty list (#32) DirPickerPlatformgainspersistedTokens, which defaults to an empty list
0.6.0 #
- Breaking: for custom
DirPickerPlatformimplementations only,pick()takes a newinitialDirectoryparameter. Apps that callDirPickerare not affected - Add
initialDirectorytoDirPicker.pick(), so the picker opens in a folder from an earlier pick:EXTRA_INITIAL_URIon Android 8+,directoryURLon iOS 13+ and macOS,IFileDialog::SetFolderon Windows,current_folder/--filename/the start folder on Linux, andstartInon the web. Platforms that can't use the given location ignore it. The example app reopens the last picked folder (#27) - Add
DirPicker.persist,DirPicker.restoreandDirPicker.releaseto keep using a picked folder after the app restarts: persisted URI permissions on Android, bookmarks on iOS, security-scoped bookmarks on macOS, and the path on Windows and Linux. Not supported on web. On Android,releasegives back a persisted permission, so apps can stay under the system's per-app limit (#31, part of #32) - Add
DirPicker.streamEntries, which emits the entries oflistEntrieswhile the folder is still being read, in batches of 200 on Android, iOS and macOS. Cancelling the subscription stops the walk.listEntriesis now built on it (#28) - Android: add
DirPicker.retrieveLostPick(). When Android destroys the Activity or kills the process while the picker is open, the picked folder is no longer dropped: call it at startup to get it, once. Other platforms returnnull(#22) DirPickerPlatformgainspersist,restore,release,streamEntriesandretrieveLostPick, with default implementations (UnimplementedErrorfor the first three, the result oflistEntriesas a stream, andnull), so existing custom implementations still compile- iOS:
pick()keeps the security scope of the picked folder open untilreleaseor the app exits, so laterlistEntriescalls use the URL the picker returned - iOS/macOS: add a privacy manifest (
PrivacyInfo.xcprivacy) declaring the file timestamp access inlistEntries(reasons3B52.1andC617.1). Before, App Store Connect could flag apps that use the plugin with ITMS-91053 (#51) - Windows: the folder dialog is now owned by the app's window, so it stays on top of it and the window can't be used until it closes. Before, it opened as a separate top-level window (#33)
- Linux: on X11, the XDG Desktop Portal dialog is now modal to the app's window (
parent_window). On Wayland, and with the zenity and kdialog fallbacks, it still opens as a separate window (#33) - Web: add
PickOptions.web(mode:, id:, startIn:), passed toshowDirectoryPicker().mode: WebPermissionMode.readwritereturns a handle that can write without asking again,idlets the browser remember the last folder per purpose, andstartInopens in a well-known folder (#34) - Web:
listEntriesnow reads files and subdirectories in parallel instead of awaiting eachgetFile()in turn (#34) - Android:
listEntriesnow reads each directory with oneDocumentsContractquery instead of going throughDocumentFile, which queried every field of every child separately. Listing 2,040 entries in the Downloads provider went from about 136 s to 1.5 s on a Galaxy Note 9, with identical results. Theandroidx.documentfiledependency is gone (#35) FileSystemEntryandIOPickedLocationnow have value equality (==andhashCode), so two listings of the same folder compare equal and locations work asSet/Mapkeys (#29)DirPickernow throws aStateErrorthat says what to do when no platform implementation is registered. Before, release builds failed with a bare null-check error (#30)- iOS/macOS:
listEntriesnow returnsnameandrelativePathin precomposed Unicode (NFC), like the other platforms. Before, names with accents such astài liệucame back decomposed (NFD) and did not compare equal to Dart strings - iOS/macOS:
listEntries(recursive: true)now throws for a missing directory or a path that is not a directory. Before, it returned an empty list - Linux:
pick()now subscribes to the portal'sResponsesignal before callingOpenFile, as the XDG portal docs recommend. Before, aResponsethat arrived before the method reply was lost andpick()never completed (#24) - Linux:
pick()now throwsException('PICKER_ERROR: …')when zenity or kdialog exit with a code other than 0 or 1, such as zenity's 5 (timeout). Before, these returnednull, as if the user had cancelled (#25) - Linux: the zenity fallback works with zenity 4 (Ubuntu 24.04 and later). It no longer passes
--ok-label, which zenity 4 rejects for file selection, soLinuxOptions.acceptLabelnow only applies to the XDG Desktop Portal. Before, zenity 4 failed andpick()returnednull - Linux/Windows:
listEntries(recursive: true)now skips the contents of a subdirectory it can't read, as iOS and macOS already did. Before, one unreadable folder made the whole call throwPathAccessException(#15) - iOS/macOS:
listEntriesnow reports a symbolic link as what it points to, as Linux and Windows do: a link to a directory hasisDirectory: true, with the target's size and date. Before, it wasisDirectory: false. Links are still not followed in recursive listings (#16) - Windows: the folder dialog now only accepts file system folders, and keeps its default options (
FOS_PATHMUSTEXIST,FOS_NOCHANGEDIR). Before, picking "This PC" or a Library returnednull, as if the user had cancelled (#17) - Windows:
pick()now throwsException('PLATFORM_ERROR: <step> failed with HRESULT 0x…')when a COM call fails. Before, every failure returnednull; only an actual cancel does now (#18) - Web:
listEntriesno longer requiresshowDirectoryPicker, so it works in Firefox and Safari for anyFileSystemDirectoryHandle, such as one from the origin private file system. Onlypick()throwsUnsupportedErrorthere (#23) pick()now throwsException('ALREADY_ACTIVE: …')when called while anotherpick()is still open. Before, on Android and iOS, one of the two Futures never completed (#19)- iOS: the picker is now presented from the top-most view controller, so
pick()works while another view controller (a sheet, an alert, another plugin's modal) is presented. Before, UIKit ignored the request and the Future never completed (#20) - Android: the picker is now launched on the main thread instead of a background thread (#21)
- Android: a pick in progress now survives a configuration change of the host Activity when the Flutter engine outlives it (cached engine, add-to-app). Before, the Future completed with
nulland the picked folder was dropped (#22) - Android: a failure to launch the picker is reported as an error (
PICKER_ERROR,NO_ACTIVITY) instead ofnull - Android: the consumer ProGuard/R8 rules now only keep
com.iamv4g.dir_picker. Before, they also kept all ofkotlinx.coroutines,kotlin.coroutinesandkotlin.jvm.internal, and turned on-keepparameternamesfor the whole app (#26) - Android: the plugin's Kotlin package is now
com.iamv4g.dir_picker(wascom.vanvixi.dir_picker), matching the GitHub account rename. The Dart API is unchanged; update any R8/ProGuard rules or native code in your app that refer to the old package - Repository, issue tracker and podspec links now point to
github.com/iamv4g
0.5.1 #
- Fix
flutter build web --wasm. The FFI/JNI implementations are now excluded withdart.library.js_interopinstead ofdart.library.html, which is false under dart2wasm (#4, authored by coco-de-dev) - Linux:
pick()now throwsUnsupportedErrorwhen no XDG Desktop Portal, zenity or kdialog is available. Before, it returnednull, which looked like a user cancel (#11) WebPickedLocationis now declared on native platforms too, solocation is WebPickedLocation(as in the README) compiles everywhere. Before, it failed with "'WebPickedLocation' isn't a type" outside the web (#12)- Allow
dbus0.8.x (#8) - Format code with the current
dart formatand silence a lint in the generated JNI bindings (#7) - Correct the Android minimum (API 24+) and the
AndroidOptions.shouldPersistdefault (false) in the README, and note Wasm support (#6)
0.5.0 #
- Breaking: Raise minimum supported SDK to Flutter 3.44 / Dart 3.12
- Migrate Android to built-in Kotlin (no longer applies the Kotlin Gradle Plugin)
0.4.1 #
- Update document
0.4.0 #
- Add
DirPicker.listEntries()to list files and directories from a previously picked location - Add
FileSystemEntrywithrelativePath, metadata, and nullable weburi - Breaking:
DirPicker.pick()now takes a singlePickOptions? optionsparameter instead of separate per-platform named parameters (androidOptions,linuxOptions,macosOptions,windowsOptions) - Breaking: Rename
SelectedLocation→PickedLocation,NativeLocation→IOPickedLocation,WebSelectedLocation→WebPickedLocation - Add
PickOptionssealed class with platform-specific factory constructors:PickOptions.android(...),PickOptions.macos(...),PickOptions.linux(...),PickOptions.windows(...) - Migrate
jnigen.yamlandffigen.yamlto Dart scripts intool/directory for better maintainability (#3, authored by alihassan143) - Update
jnidependency to1.0.0(#3, authored by alihassan143) - Update
jnigendev dependency to0.16.0(#3, authored by alihassan143) - Fix
ffigenconfiguration to support latest API changes inffigen 20.1(#3, authored by alihassan143)
Migration guide #
// Before
DirPicker.pick(androidOptions: AndroidOptions(shouldPersist: true));
DirPicker.pick(macosOptions: MacosOptions(acceptLabel: 'Open'));
// After
DirPicker.pick(options: PickOptions.android(shouldPersist: true));
DirPicker.pick(options: PickOptions.macos(acceptLabel: 'Open'));
// Before
if (location is NativeLocation) { ... }
if (location is WebSelectedLocation) { ... }
// After
if (location is IOPickedLocation) { ... }
if (location is WebPickedLocation) { ... }
0.3.1 #
- Add README usage examples for handling
WebSelectedLocationon web andNativeLocationon native
0.3.0 #
- Breaking:
DirPicker.pick()now returnsSelectedLocation?instead ofUri? - Add
SelectedLocationabstract class withNativeLocation(native platforms) andWebSelectedLocation(web) - Web: return
WebSelectedLocationwrappingFileSystemDirectoryHandle— use.handleto access directory contents via the File System Access API - Web: throw
UnsupportedErroron browsers that do not supportshowDirectoryPicker()(Firefox/Safari)
0.2.1 #
- Fix Swift Package Manager detection on pub.dev
0.2.0 #
- Add Swift Package Manager (SPM) support for iOS and macOS
- Breaking: Rename
MacosOptions.prompt→MacosOptions.acceptLabelfor consistency with other platforms - Add
MacosOptions.messageparameter to customize the panel message - Fix
AndroidOptions.shouldPersistdefault value tofalse
0.1.0 #
- Initial version