Skip to content
This repository has been archived by the owner on Mar 18, 2023. It is now read-only.

Commit

Permalink
Merge branch 'master' of https://github.com/maxieds/AndroidFilePicker…
Browse files Browse the repository at this point in the history 
…Light
  • Loading branch information
@maxieds
maxieds committed Nov 13, 2020
2 parents cebce5b + 665a6a8 commit 156bbf7
Showing 1 changed file with 66 additions and 16 deletions.
82 changes: 66 additions & 16 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,9 @@

<img src="https://jitpack.io/v/maxieds/AndroidFilePickerLight.svg" /><img src="https://img.shields.io/badge/NOTE%3A-Project%20is%20a%20work%20in%20progress-orange" /><img src="https://img.shields.io/badge/API%2029%2B-Tested%20on%20Android%2010-yellowgreen" /><img src="https://badges.frapsoft.com/os/gpl/gpl.svg?v=103" />


<img src="https://forthebadge.com/images/badges/made-with-java.svg" /><img src="https://forthebadge.com/images/badges/powered-by-coffee.svg" /><img src="https://forthebadge.com/images/badges/built-for-android.svg" />

<img src="https://badges.frapsoft.com/os/v2/open-source-175x29.png?v=103" />
<img src="https://raw.githubusercontent.com/maxieds/AndroidFileChooserLight/master/Screenshots/ReadmeEmojiBadges/HackerCatEmoji-v1.png" /><img src="https://badges.frapsoft.com/os/v2/open-source-175x29.png?v=103" /><img src="https://raw.githubusercontent.com/maxieds/AndroidFileChooserLight/master/Screenshots/ReadmeEmojiBadges/tRUTH.png" />

#### A polite request from the developer

Expand All @@ -19,8 +18,6 @@ fellow Android developers alike with a quality code base.
It will make me just *so happy* all over if you all that appreciate this source code contribution as much as I have writing it
can help me reach out to my first **100-star** repository on GitHub.

[![HitCount](http://hits.dwyl.com/maxieds/AndroidFileChooserLight.svg)](http://hits.dwyl.com/maxieds/AndroidFileChooserLight)

## About the library

A file and directory chooser widget for Android that focuses on presenting an easy to configure lightweight UI.
Expand Down Expand Up @@ -65,7 +62,7 @@ library can be included in the client Android application:
in the application *build.gradle* configuration.
* Update the project *AndroidManifest.xml* file to extend the documents provider,
request required permissions, and setup some helpful legacy file handling options for devices
targeting Android platforms with SDK < 11.
targeting Android platforms with SDK < Android OS 11.

Examples of using the library to pick files and directories from client Java code is also
included in the detailed documentation in the next section.
Expand Down Expand Up @@ -134,7 +131,7 @@ Note that unlike some samples to get other Android libraries up and running, the
to the custom ``FileProvider`` implemented by the library. It is sufficient to just use the standardized wrappers
to launch a new ``FileChooserActivity`` instance and use the file picker functionality bundled within that interface.

## Sample client Java source code
## Sample client source code in Java

The next examples document basic, advanced, and custom uses of the library in client code.
The file chooser instance is launched via a traditional ``startActivityForResult`` call
Expand All @@ -161,6 +158,13 @@ the results:
showFileChooserResultsDialog(selectedFilePaths, rteErrorMsg);
}
```
The following are the unique ``Intent`` keys that are associated with the returned data (if available):
```java
public static final String FILE_PICKER_INTENT_DATA_TYPE_KEY = "FilePickerIntentKey.SelectedIntentDataType";
public static final String FILE_PICKER_INTENT_DATA_PAYLOAD_KEY = "FilePickerIntentKey.SelectedIntentDataPayloadList";
public static final String FILE_PICKER_EXCEPTION_MESSAGE_KEY = "FilePickerIntentKey.UnexpectedExitMessage";
public static final String FILE_PICKER_EXCEPTION_CAUSE_KEY = "FilePickerIntentKey.ExceptionCauseDescKey";
```

### Basic usage: Returning a file path selected by the user

Expand Down Expand Up @@ -195,7 +199,51 @@ The next options are available to configure the non-display type (e.g., properti
file chooser that do not depend on how it looks) properties of the library.
These can be set using the ``AndroidFilePickerLight.Builder`` class as follows:
```java
/* TODO */
FileChooserBuilder fcBuilderConfig = new FileChooserBuilder.getDirectoryChooserInstance(FileChooserActivity.getInstance())
.allowSelectFileItems()
.allowSelectFolderItems()
.setDisplayUIConfig(CustomThemeBuilder uiCfg) // Reserved for future use (see docs below)
.setActionCode(int activityResultCode)
.setNavigationFoldersList(List<DefaultNavFoldersType> navFoldersList)
.showHidden(boolean enable)
.setSelectMultiple(int maxFileInsts)
.setSelectionMode(SelectionModeType modeType)
.setPickerInitialPath(BaseFolderPathType storageAccessBase)
.setActivityIdleTimeout(long timeoutMillis)
.setExternalFilesProvider(ContentProvider extFileProvider); // Reserved for future use
```
The relevant ``enum`` types that can be passed as arguments to these methods include the following:
```java
public enum SelectionModeType {
SELECT_FILE,
SELECT_MULTIPLE_FILES,
SELECT_DIRECTORY_ONLY,
SELECT_OMNIVORE
}
public enum BaseFolderPathType {
BASE_PATH_TYPE_FILES_DIR,
BASE_PATH_TYPE_EXTERNAL_FILES_DOWNLOADS,
BASE_PATH_TYPE_EXTERNAL_FILES_MOVIES,
BASE_PATH_TYPE_EXTERNAL_FILES_MUSIC,
BASE_PATH_TYPE_EXTERNAL_FILES_DOCUMENTS,
BASE_PATH_TYPE_EXTERNAL_FILES_DCIM,
BASE_PATH_TYPE_EXTERNAL_FILES_PICTURES,
BASE_PATH_TYPE_EXTERNAL_FILES_SCREENSHOTS,
BASE_PATH_TYPE_USER_DATA_DIR,
BASE_PATH_TYPE_MEDIA_STORE,
BASE_PATH_SECONDARY_STORAGE,
BASE_PATH_DEFAULT,
BASE_PATH_EXTERNAL_PROVIDER;
}
public enum DefaultNavFoldersType {
FOLDER_ROOT_STORAGE("Root", R.attr.namedFolderSDCardIcon, BaseFolderPathType.BASE_PATH_DEFAULT),
FOLDER_PICTURES("Pictures", R.attr.namedFolderPicsIcon, BaseFolderPathType.BASE_PATH_TYPE_EXTERNAL_FILES_PICTURES),
FOLDER_CAMERA("Camera", R.attr.namedFolderCameraIcon, BaseFolderPathType.BASE_PATH_TYPE_EXTERNAL_FILES_PICTURES),
FOLDER_SCREENSHOTS("Screenshots", R.attr.namedFolderScreenshotsIcon, BaseFolderPathType.BASE_PATH_TYPE_EXTERNAL_FILES_SCREENSHOTS),
FOLDER_DOWNLOADS("Downloads", R.attr.namedFolderDownloadsIcon, BaseFolderPathType.BASE_PATH_TYPE_EXTERNAL_FILES_DOWNLOADS),
FOLDER_USER_HOME("Home", R.attr.namedFolderUserHomeIcon, BaseFolderPathType.BASE_PATH_TYPE_USER_DATA_DIR),
FOLDER_MEDIA_VIDEO("Media", R.attr.namedFolderMediaIcon, BaseFolderPathType.BASE_PATH_TYPE_EXTERNAL_FILES_DCIM);
}
```

### Extending file types for filtering and sorting purposes in the picker UI
Expand Down Expand Up @@ -249,7 +297,6 @@ Here is an example of how to utilize these customized classes with the library's
```java
FileChooserBuilder fcConfig = new FileChooserBuilder();
fcConfig.setFilesListSortCompareFunction(FileFilter.FileItemsSortFunc);
// TODO

// Some defaults for convenience:
fcConfig.filterByDefaultFileTypes(List<DefaultFileTypes> fileTypesList, boolean includeExcludeInList);
Expand All @@ -263,7 +310,7 @@ This part of the library, while a primary motivator for writing it and a key fea
is still under active development. I will add in documentation showing how to customize the file
picker themes (color schemes, icons, and other properties) as they become ready to use.

#### Basic example (quickstart guide to using the file picker library)
#### Basic example (quickstart guide to using the file picker library styling options)

#### Full example (detailed usage of the current custom theme/UI display options)

Expand Down Expand Up @@ -299,25 +346,28 @@ here is the full listing and type specs for what attributes can actually be chan

### Misc other useful utilities and customizations bundled with the main library

### Displaying a visual linear bar style progress bar for slow directory loads (TODO)
#### Displaying a visual linear bar style progress bar for slow directory loads

This functionality may be useful at some point for those willing to extend this code with
custom external file providers, e.g., to read and recurse into directories on Dropbox or GitHub.
I have a simple visual Toast-like display that can be updated and/or canceled in real time to
let the user know that the directory is loading and that the client application is just "thinking"
(as opposed to freezing with a runtime error).
(as opposed to freezing with an inexplicable runtime error).

To invoke this progress bar display in realtime, consider calling the following code examples:
To invoke this progress bar display in realtime, consider calling the following
[code examples](https://github.com/maxieds/AndroidFileChooserLight/blob/master/AndroidFilePickerLightLibrary/src/main/java/com/maxieds/androidfilepickerlightlibrary/DisplayUtils.java#L159):
```java
DisplayUtils.DisplayProgressBar(String waitingOnProcessLabel, int curPos, int totalPos);
DisplayUtils.DisplayProgressBar(Activity activityInstInput, String thingsName, int curPos, int totalPos);
DisplayUtils.EnableProgressBarDisplay(true);
// ... Then whenever the long process completes, kill the progress bar update callbacks with: ...
DisplayUtils.EnableProgressBarDisplay(true);
DisplayUtils.EnableProgressBarDisplay(false);
```
In principle, the status bar is useful when the underlying operation takes longer than, say 8-10 seconds to complete.
This code is modified from a status timer to keep the user informed while scanning for a long duration read of
NFC tags on Android (see [the MFCToolLibrary](https://github.com/maxieds/MifareClassicToolLibrary) and
its demo application). The core of the progress bar is
shown by periodically posting Toast messages with a custom layout ``View``. Please post a new issue message
if anyone using this library in their own application finds this useful, or amusing too.
shown by periodically posting Toast messages with a custom layout ``View``.
**Please do post a new issue message
if anyone using this library in their own application finds this useful, or amusing too
(input and feedback from other humans is good, in general).**

0 comments on commit 156bbf7

Please sign in to comment.