FileDialog App API
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.

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:

/apps/filedialog/FileDialog.html?type=open&filter=Word%20document%20(*.doc,*.rtf)%0AC%2B%2B%20file(*.cpp,*.h,*.hpp)&browse_id=12345
Getting the Chosen File Name

When the file has been selected, FileDialog.html sends back a HTML5 message to its parent frame (the caller):

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:

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 "".