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

¿Qué es?

Es un tipo de cuadro de cuadro de diálogo usado para elegir el nombre de un archivo, similar al cuadro de diálogo
mostrado por MS Windows, pero compatible con otros entornos que no son Windows.

Algunos parámetros son configurables, como el tipo de cuadro de diálogo, el título, las extensiones de los archivos
mostrados, si se muestran directorios (carpetas) y archivos ocultos, el directorio de inicio y el nombre de
archivo por defecto.


Entrada: Acepta parámetros de similares a la función de cuadro de diálogo de la API de Windows
	 más los parámetros configurables.
Salida: ruta+nombre de archivo+extensión (o una cadena vacía si se cancela o no se elige ningún nobre de archivo)


Se ha probado en entornos Windows y Linux y parece que funciona correctamente, sin fallos importantes.

No ha sido probado en Mac OS.

Respecto a la versión 1, se ha mejorado el interfaz, haciendo emulación del doble click del botón del ratón,
se ha mejorado el tratamiento y prevención de errores, se ha hecho editable la ruta (path) actual y se ha
añadido la posibilidad de cambio de unidad de disco (sólo en verisón Windows).

Este programa ha sido desarrollado con QB64 2.0.2 e InForm 1.3


Descripción del interfaz:

	Lista de directorios (carpetas), archivos en el directorio actual,
	letra de unidad de disco (Sólo en Windows), nombre del archivo seleccionado y
	ruta actual.
	Permite moverse por la lista de directorios y la de archivos.
	Permite editar la ruta actual, para desplazarse directamente a otra
	o cambiar de unidad de disco.
	Permite seleccionar cualquier directorio o archivo con un simple click de ratón.
	Si se selecciona el nombre de un archivo, éste se muestra en el recuadro de texto.
	La emulación de doble click del ratón permite cambiar de directorio o seleccionar y
	aceptar el nombre del archivo.
	Al cambiar de directorio, se cambia la ruta y se actualiza la lista de archivos.
	Si se pulsa el botón Accept, el programa devuelve el nombre del archivo seleccionado y termina.
	Si se pulsa el botón Cancel se devuelve una cadena vacía.
	En el modo New, Save o Save as, si se elige el nombre de un archivo que ya existe, un mensaje preguntará
	si se desea sobreescribir.
	Permite la personalización del título de la ventana, el directorio de inicio que se mostrará y
	el nombre de archivo mostrado por defecto (El nombre de archivo se ignora en los modos Open).


¿Qué se necesita?

Este cuadro de diálogo no puede funcionar como programa por sí mismo. Necesita unos parámetros para funcionar
correctamente.
Sin estos parámetros, el programa no funcionará o lo hará de forma errática.
Debe ser llamado desde otro programa, (llamémosle Programa Principal), que prepare los parámetros adecuados
y lo arranque.
También se puede arrancar desde una línea de comando, pasando los parámetros.

Se incluyen estos 2 programas:

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

OpenSaveDialog2.bas - Es el principal para correr el cuadro de diálogo.

OpenSaveDialog_HostForm2.bas - Es un programa de ejemplo para arrancar correctamente OpenSavedialog2

Se necesitan QB64 e Inform (UiEditor) para compilar ambos programas.



¿Cómo funciona?

OpenSaveDialog se mostrará como una ventana emergente. El programa desde el que se llama quedará
congelado, a la espera de que termine éste.

Se puede mandejar con el ratón o con el teclado.

El usuario podrá elegir un directorio/carpeta y/o un archivo del directorio.
Se pueden filtrar los archivos según el tipo (extensión del archivo).
Se puede cambiar de unidad de disco, seleccionando la letra en la lista desplegable o tecleándola
en el cuadro de texto.
Se puede cambiar la ruta y la unidad, tecleándola en el cuadro de texto donde aparece la ruta actual.
Al hacer doble click o pulsar ENTER en el nombre de un directorio, la ruta actual se cambiará y
se actualizará la lista de directorios y archivos contenidos en el directorio, pero filtrados
por el filtro seleccionado.
 
Para aceptar el nombre del fichero elegido, se puede pulsar el botón Accept o hacer doble click
sobre él. También se puede pulsar ENTER en el cuadro del archivo seleccionado o en la lista
de archivos.
Para cancelar, pulsar el botón Cancel o cerrar la ventana.

OpenSaveDialog usa comandos de consola (shell) para leer la lista de directorios (carpetas) y los archivos.

Cuando termine, creará un archivo temporal ("__OpenSaveDialog__.tmp") en el mismo directorio donde
esté el ejecutable.
Asegurarse de que el directorio/carpeta tiene permiso de escritura.

Los archivos ocultos y de sistema se pueden mostrar opcionalmente.

El programa no comprueba la sintáxis de los parámetros en profundidad. Asegurarse de que mantienen 
la sintáxis correcta.

Los parámetros Título (title), Mostrar archivos ocultos (Show hidden files), archivo por defecto (Filename) y
ruta inicial (Start dir), son opcionales y se pueden oimitir. Estos 3 parámetros de pueden pasar en
cualquier orden, después de los parámetros oblgatorios.

El parámetro de ruta inicial, debe llevar obligatoriamente el carácter SLASH ("/"), si está trabajando
en Linux y el carácter BACKSLASH ("\").

Una vez que se muestra el cuadro de diálogo, el usuario puede elegir un nombre de archivo o teclearlo en el
cuadro de texto y pulsar el botón Accept.
Una vez hecho, la ruta (path) y el nombre el archivo se guardan en el archivo "__OpenSaveDialog__.tmp",
para que el programa principal pueda recuperarlo.

Luego, el programa principal debe leer la primera línea del archivo temporal para recuperar la ruta y el
nombre del archivo.

Si se pulsa el botón Cancel o se cierra la ventana, en el archivo temporal se escribirá una línea en blanco,
en lugar de la ruta y el nombre del archivo elegido.

Cuando se elige un archivo, ni se crea ni se sobreescribe pero, cuando se usa la opción
"New", "Save" o "Save as", si un archivo ya existe, se advierte de ello para que el usuario pueda elegir
si continuar o elegir otro.



Como se usa:

Necesitarás QB64 e Inform instalado.

Compila OpenSaveDialog2.bas en MS Windows, Linux o Mac OS.
Compila también OpenSaveDialog_HostForm2.bas si quieres probar el programa de ejemplo.

OBLIGATORIO: Si estás compilando en Linux, despues de crear el archivo ejecutable, renómbralo "OpenSaveDialog2.linux".

Esta versión soporta el doble click. No es el verdadero doble click del sistema operativo. Es emulado.

Se han parcheado las rutinas __UI_ValueChanged_ en los controles "list box" y "drop-down list box", para
evitar un bug.

Si quieres arrancar el cuadro desde tu propio programa, puedes hacerlo así:

	Consola de comandos de Windows (ejemplo):

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


	Programa compilado en 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$


	Programa compilado en 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$


	Explicación:

		ExePath$ = _StartDir$	>>> Aqui es donde está el programa ejecutable. Es para evitar crear archivos temporales en cada directorio.

		Mode%% = Modo del cuadro de diálogo (1="New", 2="Open", 3="Save", 4="Save as",5=Custom New/Save/Save As, 6=Custom Open)

		* Los modos New, Save y Save as, funcionan exactamente igual. Por defecto mostarán el título de la ventana preconfigurado.
		* Los modos personalizados (custom) mostrarán como título de la ventana, el que se especifique en el parámetro title.
		  Si no se especifica título, se mostará un título preconfigurado.

		Title$ = Texto para el título de la ventana del cuadro.

		Filters$ = Texto con la descripción de los tipos de archivo y los comodines de sus extensiones.

		* Primero vá la descripción, seguida por un carácter pipe "|" y luego la extensión o extensiones (siempre *.ext)
		  Se permiten múltiples tipos de archivo, separados por el carácter "|"
		  Las extensiones no deben ser de 3 caracteres obligatoriamente.
		  Se permite la selección de varios tipos de archivo, con varias extensiones diferentes, separadas con el
		  carácter punto y coma (";").

		Ejemplos:
		
			"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 (*.*)|*.*"


Después de elegir el nombre del archivo o cancelar, la ruta y el nombre del archivo se guardan en el archivo temporal
"__OpenSaveDialog__.tmp", en el mismo directorio donde está el ejecutable.

Para recuperar el nombre del archivo elegido, se debe abrir el archivo temporal y leer la primera línea.
Se debe usar siempre LINE INPUT # para leer el archivo, porque tanto la ruta como el nombre del archivo
pueden contener espacios.

Si se pulsó el botón Cancel o se cierró el cuadro de diálogo, entonces se leerá una línea en blanco.


Fallos conocidos:

Si el texto de la ruta de inicio no contiene una barra slash (en Linux) o una barra invertida backslash (en Windoows),
el texto se tomará como nombre de archivo.
Para evitarlo, es obligatorio que el texto de la ruta de inicio contenga este carácter.
