Starting on a more comprehensive set of user docs (besides the source code)

maxieds · web-flow · commit d19157529132 · 2020-11-13T14:59:36.000-05:00
diff --git a/README.md b/README.md
@@ -44,9 +44,7 @@ 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
 
@@ -121,6 +119,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 +155,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
@@ -174,14 +190,77 @@ These can be set using the ``AndroidFilePickerLight.Builder`` class as follows:
 ### Extending file types for filtering and sorting purposes in the picker UI
 
 
+#### Overriding the default file and directory sorting (TODO)
 
-### Configuring the client theme and UI look-and-feel properties
+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);
+
+    }
+```
 
-#### Basic example (quickstart guide to using the file picker library)
 
 
 
+### Configuring the client theme and UI look-and-feel properties
 
+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 +302,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 +318,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);
-
-    }
-```
