1 files changed, 21 insertions, 0 deletions
diff --git a/ppapi/api/dev/ppb_file_chooser_dev.idl b/ppapi/api/dev/ppb_file_chooser_dev.idl
index cd5678c..c545a041 100644
--- a/ppapi/api/dev/ppb_file_chooser_dev.idl
+++ b/ppapi/api/dev/ppb_file_chooser_dev.idl
@@ -76,6 +76,17 @@ interface PPB_FileChooser_Dev {
    * with a file (or files) selected, PP_ERROR_USERCANCEL if the user selected
    * no file, or another error code from pp_errors.h on failure.
    *
+   * <b>Subtle note:</b> This function will only work when the tab containing
+   * the plugin is visible. Show will fail if the tab is in the background.
+   * Since it's not normally possible to get input events while invisible, this
+   * is not an issue. But there is a race condition because events are
+   * processed asynchronously that authors should be aware of. If the user
+   * clicks and switches tabs very quickly, a plugin could believe the tab is
+   * visible while Chrome believes it is invisible and the Show() call will
+   * fail. This will not generally cause user confusion since the user will
+   * have switched tabs and will not want to see a file chooser from a
+   * different tab.
+   *
    * @param[in] chooser The file chooser resource.
    * @param[in] callback A <code>CompletionCallback</code> to be called after
    * the user has closed the file chooser dialog.
@@ -112,6 +123,16 @@ interface PPB_FileChooser_Dev {
    * with a file (or files) selected, PP_ERROR_USERCANCEL if the user selected
    * no file, or another error code from pp_errors.h on failure.
    *
+   * <b>Subtle note:</b> This function will only work when the tab containing
+   * the plugin is visible. Show() will fail if the tab is in the background.
+   * Since it's not normally possible to get input events while invisible, this
+   * is not normally an issue. But there is a race condition because events are
+   * processed asynchronously. If the user clicks and switches tabs very
+   * quickly, a plugin could believe the tab is visible while Chrome believes
+   * it is invisible and the Show() call will fail. This will not generally
+   * cause user confusion since the user will have switched tabs and will not
+   * want to see a file chooser from a different tab.
+   *
    * @param[in] chooser The file chooser resource.
    *
    * @param[in] output An output array which will receive PP_Resource(s)