FilePickerDemo

FilePickerDemo screen shot.

1 Introduction
fnFilePicker is an open source module that can be used in a rfo-basic program. It implements a dialog which allows the user to select a file or directory from the Android file system. It shows a list of all of the files and subdirectories found in a specified directory. It then allows you to navigate through the file system. It will then return the name of the file or directory that was selected from the list.
fnFilePicker was written in rfo-basic and uses the GW library. It consists of three user defined functions which are contained in a single file called fnFilePicker.bas. FilePickerDemo is a program that demonstrates the functionality of fnFilePicker.

2 Distribution
fnFilePicker is distributed as a zip file called FilePickerDemo.zip. It contains the following:

Name	Description
FilePickerDemo.bas	Demo program to test fnFilePicker.bas
fnFilePicker.bas	fnFilePicker functions.
fnFilePicker.html	Program documentation.
fnTally.bas	String function user by fnFilePicker.bas
fnInstr.bas	String function user by fnFilePicker.bas
fnBinary.bas	String function user by FilePickerDemo.bas
GW.bas	Graphical User Interface library.

fnTally.bas, fnInstr.bas and fnBinary.bas are string functions developed by me. Each file contains commented documentation.

FilePickerDemo.bas was also written by me. It demonstrates all of the features of fnFilePicker.

3 How to Use fnFilePicker in Your Software.
There are three functions that you can use in your rfo-basic program. They are described in the following sections.

3.1 ADD_FILEPICKER()

Syntax:	ctl_id = ADD_FILEPICKER (page_id)
Parameters:	page_id	Page ID.
Returns:	ctl_id	Control ID.

Before a fnFilePicker dialog can be used, it has to be added to a page that was previously created. This function will create a fnFilePicker and return the new control's ID.

Example:
% Must use the GW library.
INCLUDE "GW.bas"

% Include the fnFilePicker module. It will include other modules as needed.
INCLUDE "fnFilePicker.bas"

% Create a new page.
MyPage = GW_NEW_PAGE()

% Add the fnFilePicker dialog.
ADD_FILEPICKER(MyPage)

% Add whatever else you need on your page.

% Display the page.
GW_RENDER(MyPage)

% Continue with the rest of your program.

3.2 SHOW_FILEPICKER$()

Syntax:	name$ = SHOW_FILEPICKER$(ctl_id, title$, path$, flags, ext$[], exc$[])
Parameters:	ctl_id	Control ID returned by a previous ADD_FILEPICKER().
	title$	String with title displayed at top of dialog.
	path$	Starting path.
	flags	Option flags
	ext$[]	String array of allowed extensions.
	exc$[]	String array of excluded file Names.
Returns:	name$	String of selected file or directory.

After the page has been rendered, your program can invoke the fnFilePicker dialog.

The third parameter, path$, specifies the path to the directory that fnFilePicker will first display. If this parameter is passed by reference, &path$, then when the user selects a file, this parameter will contain the path to that file. If the parameter is empty (""), the rfo-basic default path will be used ("../data/"). This parameter is updated as you navigate through the file system. It is always displayed at the top of the dialog, just under the title.

The fourth parameter, flags, is actually a four-bit number. Each bit is a flag, so each flag can be set to either 0 or 1. Each flag's name and description are as follows.

Bit number	Hex nibble	Flag name
3	1000	FP_WRITE_IN
2	0100	FP_ABSOLUTE
1	0010	FP_DIRS_ONLY
0	0001	FP_NAVIGATE

The flags are defined in the code this way:
FP_NAVIGATE = 1
FP_DIRS_ONLY = 2
FP_ABSOLUTE = 4
FP_WRITE_IN = 8

FP_NAVIGATE: If is set to 1, then fnFilePicker will prepend ".." to the beginning of the file list. This entry can be selected by the user to navigate to the parent directory. This entry will be followed by all subdirectories, in alphabetical order, with "(d)" after each subdirectory name. Then the files will be listed, in alphabetical order. However, if FP_NAVIGATE is reset to 0, then only the files will be listed. Navigation will not be allowed since neither the ".." entry nor the subdirectories will be listed.

FP_DIRS_ONLY: If set to 1, then fnFilePicker will only display directory names. However, there will also be an entry at the top of the list which will say "(SELECT THIS DIRECTORY)". The purpose of this mode is to allow the user to select a directory name, rather than a file name. The user has to navigate to the desired directory so that its contents will be listed. Then the SELECT item should be picked.

FP_ABSOLUTE: The path is displayed (and optionally returned in the path$ parameter) as the user navigates through the file system. If FP_ABSOLUTE is reset to 0, the path will be relative to the default "rfo-basic/data" path. If FP_ABSOLUTE is set to 1, then the path will be absolute.

FP_WRITE_IN: There are times when the user must be allowed to either select an existing file or specify (write-in) a new file name. If FP_WRITE_IN is set to 1, then an input box will appear above the file list, along with an item that says "(SELECT ABOVE)".

The fifth parameter, ext$[], is an array that can contain file extensions. Only files that have with extensions contained in the array will be listed by fnFilePicker. Files with extensions not contained in the array will not be listed by fnFilePicker. However, if the array contains only one empty element (""), then all files will be listed regardless of their extensions.

The sixth parameter, exc$[], is an array that can contain file names (name plus extension). fnFilePicker will ignore and not list any files matching any of the array elements. However, if the array contains only one empty element (""), then no files will be excluded.

The returned parameter will be the name of the file selected by the user, or an empty string if no file was selected.

3.3 GET_FILEPICKER_VER$()

Syntax:	version$ = GET_FILEPICKER_VER$()
Returns:	version$	String with fnFilePicker version.

This function returns the version number of the fnFilePicker module.

4 Disclaimer
The fnFilePicker module and its documentation are provided with no warranty. Although the author will make an effort to ensure correctness, the software and documentation are provided "as is", with any faults, defects, bugs, and errors.

5 Credits
This software and documentation was written by Robert A. Rioja, robrioja@gmail.com, http://www.Rioja-Tech.com

The GW Library was written by Nicolas Mougin, mougino@free.fr, http://mougino.free.fr

You can run FilePickerDemo two different ways:

You can download the source files and run it with the RFO-Basic interpreter. You must have already installed RFO-Basic on your Android device. Then you can download the FilePickerDemo source files from the next section and copy them into the approriate RFO-Basic folders in your Android device.

You can download the compiled version of FilePickerDemo in APK format from this site. Then you can install it on your Android device without the need for the RFO-Basic interpreter app. This APK was produced using the BASIC! Compiler written by mougino.

Release History

Version	Date	Description	Source	APK
20210319	March 19, 2021	First release.	Downloaded 82 times	Downloaded 130 times

Hope you enjoy using FilePickerDemo!