Merge branch 'master' of https://github.com/maxieds/AndroidFilePickerLight

Author: maxieds

README.md

@@ -10,6 +10,17 @@
 
 <img src="https://badges.frapsoft.com/os/v2/open-source-175x29.png?v=103" />
 
+#### A polite request from the developer
+
+In the event that this library and the documentation of new Android features this code provides is useful, please 
+:star::star::star::star::star: my application. I have taken my free time on this project to 
+*Hack for freedom with free software (TM, so to speak, as I like to say it)* by providing users and 
+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.
@@ -44,11 +55,9 @@ Key features in the library include the following:
 
 ### Screenshots of the library in action (Default theme)
 
-<img src="https://raw.githubusercontent.com/maxieds/AndroidFileChooserLight/master/Screenshots/WorkingUI-Screenshot_20201112-052224.png" width="250" /><img src="https://raw.githubusercontent.com/maxieds/AndroidFileChooserLight/master/Screenshots/WorkingUI-Screenshot_20201113-134724.png" width="250" /><img src="" width="250" />
-
-<img src="" width="250" /><img src="" width="250" /><img src="" width="250" />
+<img src="https://raw.githubusercontent.com/maxieds/AndroidFileChooserLight/master/Screenshots/WorkingUI-Screenshot_20201112-052224.png" width="250" /> <img src="https://raw.githubusercontent.com/maxieds/AndroidFileChooserLight/master/Screenshots/WorkingUI-Screenshot_20201113-134724.png" width="250" /> <img src="https://raw.githubusercontent.com/maxieds/AndroidFilePickerLight/master/Screenshots/SampleApplicationDemo-ProgressBarDisplay.png" width="250" />
 
-## Including the library in an Android application
+## Including the library for use in a client Android application
 
 There are a couple of quickstart items covered in the sections below to handle before this
 library can be included in the client Android application:
@@ -121,6 +130,9 @@ that the application set the option
      <!-- Complete the internals of the application tag (activities, etc.) below -->
 </application>
 ```
+Note that unlike some samples to get other Android libraries up and running, there is no need to define references 
+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
 
@@ -154,12 +166,27 @@ the results:
 
 This is a quick method to select a file and/or directory picked by the user:
 ```java
-public void actionButtonLaunchSingleFilePickerActivity(View btnView) {
+    public void actionButtonLaunchSingleFilePickerActivity(View btnView) {
         FileChooserBuilder fpInst = FileChooserBuilder.getDirectoryChooserInstance(this);
         fpInst.showHidden(true);
+        fpInst.setPickerInitialPath(FileChooserBuilder.BaseFolderPathType.BASE_PATH_DEFAULT);
+        fpInst.launchFilePicker();
+    }
+    public void actionButtonLaunchSingleFilePickerActivity(View btnView) {
+        FileChooserBuilder fpInst = FileChooserBuilder.getSingleFilePickerInstance(this);
+        fpInst.showHidden(true);
         fpInst.setPickerInitialPath(FileChooserBuilder.BaseFolderPathType.BASE_PATH_TYPE_EXTERNAL_FILES_SCREENSHOTS);
         fpInst.launchFilePicker();
     }
+    public void actionButtonLaunchOmnivorousMultiPickerActivity(View btnView) {
+        FileChooserBuilder fpInst = new FileChooserBuilder(this);
+        fpInst.setSelectionMode(FileChooserBuilder.SelectionModeType.SELECT_OMNIVORE);
+        fpInst.setSelectMultiple(5);
+        fpInst.setActionCode(FileChooserBuilder.ACTIVITY_CODE_SELECT_MULTIPLE_FILES);
+        fpInst.showHidden(true);
+        fpInst.setPickerInitialPath(FileChooserBuilder.BaseFolderPathType.BASE_PATH_TYPE_EXTERNAL_FILES_DOWNLOADS);
+        fpInst.launchFilePicker();
+    }
 ```
 
 ### Detailed list of non-display type options
@@ -173,15 +200,70 @@ These can be set using the ``AndroidFilePickerLight.Builder`` class as follows:
 
 ### Extending file types for filtering and sorting purposes in the picker UI
 
+Many other good file chooser libraries for Android implement extendable ways for users to filter, 
+select and sort the files that are presented to the user. We choose to offer the same extendable 
+functionality here while staying tightly coupled with more Java language standard constructs. 
 
+The following is an example of how to create a custom file filter for use with this library. 
+The full interface specification is found in the source file 
+[FileFilter.java](https://github.com/maxieds/AndroidFileChooserLight/blob/master/AndroidFilePickerLightLibrary/src/main/java/com/maxieds/androidfilepickerlightlibrary/FileFilter.java#L35):
+```java
+    public static class FileFilterByRegex extends FileFilterBase {
+        private Pattern patternSpec;
+        public FileFilterByRegex(String regexPatternSpec, boolean inclExcl) {
+            patternSpec = Pattern.compile(regexPatternSpec);
+            setIncludeExcludeMatchesOption(inclExcl);
+        }
+        public boolean fileMatchesFilter(String fileAbsName) {
+            if(patternSpec.matcher(fileAbsName).matches()) {
+                return includeExcludeMatches == INCLUDE_FILES_IN_FILTER_PATTERN;
+            }
+            return includeExcludeMatches == EXCLUDE_FILES_IN_FILTER_PATTERN;
+        }
+    }
+```
+The main interface in the base class for the example above extends the stock Java ``FilenameFilter``
+interface. There is a difference in what our derived classes must implement. Namely, subject to the 
+next defines, the code can decide whether to include or exclude the file matches based on whether the 
+filename filter matches the user specified pattern: 
+```java
+static final boolean INCLUDE_FILES_IN_FILTER_PATTERN = FileChooserBuilder.INCLUDE_FILES_IN_FILTER_PATTERN;
+static final boolean EXCLUDE_FILES_IN_FILTER_PATTERN = FileChooserBuilder.EXCLUDE_FILES_IN_FILTER_PATTERN;
+```
+Similarly, an overloaded sorting class that can be extended is sampled below:
+```java
+    public static class FileItemsSortFunc implements Comparator<File> {
+        public File[] sortFileItemsList(File[] folderContentsList) {
+            Arrays.sort(folderContentsList, this);
+            return folderContentsList;
+        }
+        @Override
+        public int compare(File f1, File f2) {
+            // default is standard lexicographical ordering (override the compare functor base classes for customized sorting):
+            return f1.getAbsolutePath().compareTo(f2.getAbsolutePath());
+        }
+    }
+```
+Here is an example of how to utilize these customized classes with the library's core 
+``FileChooserBuilder`` class instances:
+```java
+FileChooserBuilder fcConfig = new FileChooserBuilder();
+fcConfig.setFilesListSortCompareFunction(FileFilter.FileItemsSortFunc);
+// TODO
+
+// Some defaults for convenience:
+fcConfig.filterByDefaultFileTypes(List<DefaultFileTypes> fileTypesList, boolean includeExcludeInList);
+fcConfig.filterByMimeTypes(List<String> fileTypesList, boolean includeExcludeInList);
+fcConfig.filterByRegex(String fileFilterPattern, boolean includeExcludeInList);
+```
 
 ### Configuring the client theme and UI look-and-feel properties
 
-#### Basic example (quickstart guide to using the file picker library)
-
-
-
+This part of the library, while a primary motivator for writing it and a key feature it aims to have, 
+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)
 
 #### Full example (detailed usage of the current custom theme/UI display options)
 
@@ -223,9 +305,7 @@ This functionality may be useful at some point for those willing to extend this
 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). The stock progress bar looks something like the following screenshot: 
-
-<img src="https://raw.githubusercontent.com/maxieds/AndroidFilePickerLight/master/Screenshots/SampleApplicationDemo-ProgressBarDisplay.png" width="250" />
+(as opposed to freezing with a runtime error).
 
 To invoke this progress bar display in realtime, consider calling the following code examples:
 ```java
@@ -241,63 +321,3 @@ 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.
 
-#### Overriding the default file and directory sorting (TODO)
-
-An example of how to do this is already seen by glancing through the sources. 
-In particular, we define an extendable base class as follows: 
-```java
-        public static class FileItemsSortFunc implements Comparator<File> {
-            public File[] sortFileItemsList(File[] folderContentsList) {
-                Arrays.sort(folderContentsList, this);
-                return folderContentsList;
-            }
-            @Override
-            public int compare(File f1, File f2) {
-                // default is standard lexicographical ordering (override the compare functor base classes for customized sorting):
-                return f1.getAbsolutePath().compareTo(f2.getAbsolutePath());
-            }
-        }
-```
-Subclasses that override the method above are free to sort the file 
-contents in the order that they are best displayed in the client application. 
-Some examples would be to override the default of placing directories at the top of the 
-files list, to perform a case-insensitive lexicographical sort (like happens on many Linux), 
-or otherwise to prioritize the file rankings where the most importantly valued presentations 
-are shown first. 
-
-Note that in the source the custom objects to filter (match, then include/exclude) the full 
-directory listings, and then sort those files that remain are applied together. See, for example, 
-the next code:
-```java
-        public static class FileFilterByRegex extends FileFilterBase {
-            private Pattern patternSpec;
-            public FileFilterByRegex(String regexPatternSpec, boolean inclExcl) {
-                patternSpec = Pattern.compile(regexPatternSpec);
-                setIncludeExcludeMatchesOption(inclExcl);
-            }
-            public boolean fileMatchesFilter(String fileAbsName) {
-                if(patternSpec.matcher(fileAbsName).matches()) {
-                    return includeExcludeMatches == INCLUDE_FILES_IN_FILTER_PATTERN;
-                }
-                return includeExcludeMatches == EXCLUDE_FILES_IN_FILTER_PATTERN;
-            }
-        }
-```
-
-#### Extending the inclusion/exclusion mechanism of files by type
-
-The specification (by Java interface and a few utility derived instances) are found in the 
-library source file ``FileFilter.java``. The bulk of the interface is reproduced as 
-follows:
-```java
-    public interface FileFilterInterface {
-
-        static final boolean INCLUDE_FILES_IN_FILTER_PATTERN = FilePickerBuilder.INCLUDE_FILES_IN_FILTER_PATTERN;
-        static final boolean EXCLUDE_FILES_IN_FILTER_PATTERN = FilePickerBuilder.EXCLUDE_FILES_IN_FILTER_PATTERN;
-
-        void    setIncludeExcludeMatchesOption(boolean includeExcludeParam);
-        boolean includeFileInSearchResults(FileTypes.FileType fileItem);
-        boolean fileMatchesFilter(FileTypes.FileType fileItem);
-
-    }
-```