OpenSave Dialog Box v. 2
''''''''''''''''''''''''


What is is?

This is a kind of dialog box used to choose a file name, similar to the ones shown in MS Windows, but compatible with
other operating systems.

Some parameters are configurable, such as dialog box type, title, file types shown, whether hidden files and 
directories (folders) are shown or not, start directory and default file name.


In: It accepts similar parameters as the dialog box function in Windows API.
Out: Path+file name+extension (or an empty string if it is cancelled or non file name is chosen)

It has been tested in Windows and Linux environments and seems to work correctly, with no important faults.

It has not been tested in Mac OS.

After version 1, interface has been improved, using double click emulation, control and prevention of errors
is improved too, path can be edited now and drive change is possible (Windows version only).

This program was developed on QB64 2.0. and InForm 1.3



Interface description:

	Directory list (folders), files in current directory, drive letter (Windows only), selected file name
	and current path.

	It is possible to change directory and select files.
	Current path can be changed, to directly move to different path or change drive letter.
	It allows to select any directory or file with a single click.
	If a file name is selected, it is shown in the file name box.
	Double ckick is emulated, to easily change directory or accept a file name.
	If directory is changed, file list is updated.
	If Accept button is clicked, the program outputs selected file name and ends.
	If Cancel button is clicked, then a blank string is outputted.
	When in New, Save or Save as mode, if the selected filename already exists, then a message
	will warn about it and will ask if the user wants to overwrite.
	Window title, start directory and default file name can be customized. File name is ignored if
	Open mode is selected.



What is needed?

This dialog box cannot work as a standalone program. It needs some parameters to work properly.
Without these parameters, it will not work at all or will behave randomly.

It must be started from another program (let's name it after Main Program), that should prepare the correct
parameteres and launch it.
It can be started from a command line, providing the needed parameters.

Two programas are included in the package:

	OpenSaveDialog2.bas + OpenSaveDialog2.frm
	OpenSaveDialog_HostForm2.bas + OpenSaveDialog_HostForm2.frm

OpenSaveDialog2.bas - This is the dialog box itself.

OpenSaveDialog_HostForm2.bas - This is a sample program to show how to properly start OpenSavedialog2

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



How does it work?

OpenSaveDialog2 will show as a pop-up window. The program it was started from, will stay frozen,
waiting for it to end.

It can be controlled either with keyboard or mouse.

User can choose a drive letter, directory/folder and a file name.
Different file types can be chosen, depending on the file extension (or file exensions)
Drive letter can be changed (Windows only), using the drive list or typing it into the
path box.

Current directory can be changed just double-clicking on any directory name or seleting a directory
name and pressing ENTER. Then, file list will be updated, based on the file type selected.
To go back to the directory before, user must click in the double-dot.

If user wants to see different file types, then file type list must be used.

To accept a file name, the user must press ENTER, click on Accept button or double-click on
the file name in the list.
To cancel, just press Cancel button.

OpenSaveDialog2 uses console commands (shell) to read directory list (folders) and file names.

At the end of the program, a temporary file will be created ("__OpenSaveDialog__.tmp"), in the same
directory where the executable file is located.
Make sure that the directory has write premissions enabled.

Hidden files can be shown as an option.

Regarding the parsed parameters, this program does basic syntax checks. Make sure to keep a correct
syntax.

Title, Show hidden files, default file name and start directory are optional parameters. They can be omitted.
These 3 parameters can be parsed in any order (always after the first 3 parameters).

Start directory parameter must have a SLASH or BACKSLACH character on it. If working on Linux, slash ("/")
character must be included. If working on Windows, a backslash character must be included ("\").

When dialog box is shown, user can choose a filename or type it in the text box and click Accept button.
Then, current path and filename are stored in file "__OpenSaveDialog__.tmp", so the main program can retrieve it.

After that, main program must read the first line from temporary file, to get the path and the file name.

If Cancel button si clicked or the window is closed, an empty line will be written, instead of the path and
file name of the selected file.

Whenever a file is selected, it is not created nor overwritten but, when using "New", "Save" or "Save as"
options, if file already exists, a warning message is shown, so the user can choose whether to continue
or to choose a different one.



How to use:

You will need QB64 installed.

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

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

This version supports double click. It is not the actual double-click on your OS. It is emulated.

__UI_ValueChanged_ routines are patched to avoid a bug in List box and drop-down list controls.

To start the dialog box from you own program, you can do it this way:

	Windows system console (Example):

		1 "New Project" "Graphic files (*.png;*.bmp;*.jpg)|All files (*.*)|*.*" "c:\users" "picture.png" 1


	Compiled program in Windows:

		Shell Chr$(34) + ExePath$ + "OpenSaveDialog2" + Chr$(34) + " " + _
    			Str$(Mode%%) + " " + Chr$(34) + Title$ + Chr$(34) +" " + Chr$(34) + filters$ + Chr$(34)+" "+_
                	chr$(34)+StartDir$+chr$(34)+" "+chr$(34)+Filename$+chr$(34)+" "+Hidden$


	Compiled program in Linux:

		Shell Chr$(34) + ExePath$ + "./OpenSaveDialog2.linux" + Chr$(34) + " "+_
	    		Str$(Mode%%) + " " + Chr$(34) + Title$ + Chr$(34) +" " + Chr$(34) + filters$ + Chr$(34)+" "+_
        	        chr$(34)+StartDir$+chr$(34)+" "+chr$(34)+Filename$+chr$(34)+" "+Hidden$


	Meaning:

		ExePath$ = _StartDir$	>>> Location of the exe file. This is to avoid create several temporary files in every directory.

		Mode%% = Dialog box mode (1="New", 2="Open", 3="Save", 4="Save as",5=Custom New/Save/Save As, 6=Custom Open)

		* New, Save and Save as modes, all work exactly the same. Default window title will be shown.
		* Custom modes will use title parameter as window title.
		  If no title is specified, a pre-configured title will be shown instead.

		Title$ = Text to show as window title.

		Filters$ = Text with file description and wildcards and extensions.

		* Description must be first, then a pipe character "|" and the wildcards and extensions (always *.ext).
		  Multiple file types are alowed, separated by the character "|".
		  Extensions of other than 3 characters are alowed.
		  Several file types, with different file extensions are alowed. They must be separated with 
		  a semicolon caracter character  ";"

		Examples:
		
			"Project (*.mpr)|*.mpr|Jpeg files (*.jpg)|*.jpg|AS files (*.as)|*.as|All files (*.*)|*.*"
			"Text files|*.txt|Documents|*.doc;*.docx|Graphic files (*.png;*.bmp;*.jpg)|All files (*.*)|*.*"

After choosing a file name or cancel, the path and the file name are saved in the temporary file "__OpenSaveDialog__.tmp",
in the same directory where the executable file is.

To retrieve the selected file name, temporary file must be open and read the first line.
It is mandatory to use LINE INPUT# to read file, as both path and file name can contain space characters.

If Cancel button was clicked or dialog window was closed, then an empty line will be read.

Known bugs:

If start directory text does not contain a slash (Linux) or backslash (Windows) character, the text will be interpreted
as file name.
To avoid this, a slash or backslash must be included in the start directory text.