document: FileDialog App API

group: Introduction

The FileDialog app contains just one file FileDialog.html, which relies on the
shipped FileBrowser app to provide the dialog window. (We can switch later to another undelying app,
but the communication with FileDialog.html must remain the same.)

FileDialog.html is designed to be embedded inside iframes.

group: Creating a File Dialog
       
Create an iframe with the URL pointing to FileDialog.html with a query string
containing the following 3 arguments:

type - dialog type: "open", "save", "dir" (the latter is for choosing a directory, not a file)
filter - a string containing descriptions of file filters to look for;
         each description is some text followed by file masks in parentheses;
         filters are delimited by \n (%0A), extensions are delimited by ","; all
         blanks, pluses, and other non-URI characters must be escaped (e.g., "C++ file" => "C%2B%2B%20file")

         Example:  "Word%20document%20(*.doc,*.rtf)%0AC%2B%2B%20file(*.cpp,*.h,*.hpp)", which
         decodes to "Word document (*.doc,*.rtf)\nC++ file(*.cpp,*.h,*.hpp)".
browse_id - some id representing the file browse dialog; can be used to distinguish multiple
            dialogs when the return value is recevied via a HTML5 message; a good suggestion is to
            use the current timestamp

URL example for the FileDialog.html iframe:
---code---
/apps/filedialog/FileDialog.html?type=open&filter=Word%20document%20(*.doc,*.rtf)%0AC%2B%2B%20file(*.cpp,*.h,*.hpp)&browse_id=12345
----------

group: Getting the Chosen File Name

When the file has been selected, FileDialog.html
sends back a HTML5 message to its parent frame (the caller):
---code---
window.parent.postMessage({protocol:"file_dialog_result", browse_id:"{passed_browse_id}", result: <chosen_file_name_relative_to_user's_home>}, "*");
----------

If the Cancel button is pressed, the message will be:
---code---
window.parent.postMessage({protocol:"file_dialog_result", browse_id:"{passed_browse_id}", result: ""}, "*");
----------

The parent must also check when the embedded FileDialog iframe is being removed from the screen
(e.g., when the user clicks the "x" button of a window/div border, which contains the iframe).
In this case, FileDialog.html sends nothing to the parent: the parent has to catch that
event by its own and assume the result is "".
