OpenSave Dialog Box v. 1
''''''''''''''''''''''

What is this?

This is a kind of dialog box to choose a file name that simulates MS Windows style dialog box, but compatible with 
non-Windows environments.

Some parameters are configurable, such as title, type of dialog box and file extension filters.


In: It will accept parameters in a similar way as the Windows API function for dialog box.
Out: Path+filename+extension (or a blank string if cancel button is pressed or no file name is chosen).


I has been tested in both MS Windows and Linux OSes and seems to not have big bugs.

It has not been tested in Mac OS.

Some routines inspired in "Inform" source code (By Fellippe Heitor)



Interface description:

	List of directories and files.
	User can browse through directories and files.
	A simple mouse click to select a file or a directory.
	Whether a file name is selected, it is shown in the textbox.
	Whether a directory/folder name is selected, path is changed
	and file list is updated.
	Press Accept buton to output the chosen file name and end program.
	Press Cancel to output a blank string.
	In modes New, Save or Save as, if the chosen file name already exists,
	then a message will ask whether overwrite or not.



What is needed?

Dialog box cannot work as a stand-alone program. It needs some parameters in the command-line to properly work.
Without the proper parameters, the program will not work or will behave buggy.
It must be started from another program (let's name it after Main Program), that must prepare the correct
parameters and start it.

There are 2 programs included:

	OpenSaveDialog.bas + OpenSaveDialog.frm
	OpenSaveDialog_HostForm.bas + OpenSaveDialog_HostForm.frm

OpenSaveDialog.bas - This is the program to run the dialog box

OpenSaveDialog_HostForm.bas - This is a sample program that shows how to properly start OpenSavedialog

QB64 and Inform (UiEditor) are needed to compile both programs.



How does it work?

OpenSaveDialog will show a pop-up window. The main (host) program will remain frozen, waiting for the dialog
box to finish.

Then, user cna choose a path and a file inside the path (or type a file name).
To select a particular file type, user can choose between different file extensions.
To accept selected file name, click on Accept button. To cancel selection, click on Cancel or close button.

Keyboard can be used too.

OpenSaveDialog uses shell commands to get file list and diretories (folders) lists.

A temporary file ("__OpenSaveDialog__.tmp") will be created in the same directory where the executable file is.
Make sure directory/folder has write permission enabled.

Hidden files or system files should not be shown by default. This cannot be changed. It will be an option
in future releases.

The program does not make complex syntax analysis. Make sure you use extrict syntax when parsing parameters.
There are no optional parameters. All of them must be parsed.

After the dialog box is shown, user can choose a file or type a file name in the text box and press
Accept button.
After that, chosen path and filename will be saved in the temporary file "__OpenSaveDialog__.tmp",
so host program can retrieve it.

Then, host program has to open the temporary file and read the first line to get the chosen path and file name.

If Cancel or Close button is clicked, then an empty file name is written in the temporary file.

Whenever a file name is chosen, no file is created or overwritten but, when using the "New", "Save"
and "Save as" option, if file already exists, a warning message is shown, so user can choose whether to continue
or choose a different file name.



How to use:

QB64 and Inform need to be installed.

Compile OpenSaveDialog.bas in MS Windows, Linux or Mac OS.
Also, compile OpenSaveDialog_HostForm.bas, if you want to test the sample program.

MANDATORY: If you are compiling on Linux, after compiling the executable file , rename it to "OpenSaveDialog.linux"

In the dialog box, ALWAYS USE SIMPLE CLICK to select both files or folders.
Double click is not supported in this version. This is to avoid a bug in the "list box" and "drop-down list box" 
controls. This will be fixed in future versions.
Double click will not be filtered, so two clicks will be processes instead.

If you want to use it from your own program, you can start it like this:


	MS Windows Command prompt (example):

		OpenSaveDialog 1 "New Project" "Project (*.mpr)|*.mpr|Jpeg files (*.jpg)|*.jpg|AS files (*.as)|*.as|All files (*.*)|*.*"


	MS Windows:

	    Shell Chr$(34) + ExePath$ + "OpenSaveDialog" + Chr$(34) + Str$(Mode%%) + " " + Chr$(34) + Title$ + Chr$(34) + " " + Chr$(34) + Filters$ + Chr$(34)

    
	Linux:

	    Shell Chr$(34) + ExePath$ + "./OpenSaveDialog.linux" + Chr$(34) + Str$(Mode%%) + " " + Chr$(34) + Title$ + Chr$(34) + " " + Chr$(34) + Filters$ + Chr$(34)


	Both Windows and Linux:

		$If WIN Then
			Shell Chr$(34) + ExePath$ + "OpenSaveDialog" + Chr$(34) + Str$(Mode%%) + " " + Chr$(34) + Title$ + Chr$(34) + " " + Chr$(34) + Filters$ + Chr$(34)
		$Else
			Shell Chr$(34) + ExePath$ + "./OpenSaveDialog.linux" + Chr$(34) + Str$(Mode%%) + " " + Chr$(34) + Title$ + Chr$(34) + " " + Chr$(34) + Filters$ + Chr$(34)
		$End If


	Explanation:

		ExePath$ = _StartDir$	>>> This is where the main exe file is alocated, to avoid a temporary files in every folder.

		Mode%% = Mode of the dialog box (1="New", 2="Open", 3="Save", 4="Save as")

		* All modes New, Save and Save as work exactly the same.

		Title$ = String as title shown in the dialog window.

		Filters$ = String of file types description and wildcards for file extensions.

		* File descrition must be first, then followed by a pipe character "|" and then by the wildcard for
		  the file extension (Always *.ext)
	  	Multiple file types are alowed, separated by character "|"

		Example:
			"Project (*.mpr)|*.mpr|Jpeg files (*.jpg)|*.jpg|AS files (*.as)|*.as|All files (*.*)|*.*"

After file name is accepted or cancel button is pressed, path + file name are saved in teporary file
"__OpenSaveDialog__.tmp", in the same folder where OpenSaveDialog executable is located.

To get the chosen file name, just open the temporary file an read the first line.
Always use LINE INPUT # to read file, as spaces can be found in the directory or file names.

If Cancel button is clicked or dialog box is closed, then an empty file name is gotten from the temporary file.



Known Bugs:

Sometimes, if Dialog box window is closed before any file is chosen, a wrong file name can be parsed
into "__OpenSaveDialog__.tmp" file, or even cannot be created at all.

This bug is left not fixed by default, as the intention of this program is to be light.

In MS Windows version, user cannot browse through different drives.
This option is not available in this version, in order to keep program small.
It will be implemented in further versions.