File dialogs

Append the supplied string to the selected file. Use it for a log or growing text document. Include your own newline when each appended entry should occupy a separate line.

Delete the selected document and invalidate the handle used for this call. Use it to remove a document that your script no longer needs. Deletion changes the selected storage location, so do not treat it as merely closing the handle.

Get the display name associated with a selected file or folder. Use the name in an import list, progress message, or export confirmation. Keep the Document handle for file operations; its display name alone does not identify a workspace file.

Check whether this selected document represents a file. Use it when browsing a selected folder so your script only attempts reads on files.

Check whether this selected document represents a folder. Use it when browsing a selected folder so your script only attempts directory operations on folders.

Get the children of a selected folder as document handles. Use it to build a folder browser or collect documents for an import. Each result is another Document, so inspect its type before reading it or listing its children.

Create a child folder inside the selected folder and return its handle. Use it to organize exports beneath a folder the user selected. The returned handle can be listed or used to create another level of folders.

Read the contents of a file selected through a document dialog. Use it to import text or binary data after the user selects a file. Decode the returned string separately when the contents are JSON or another structured format.

Replace the contents of the selected file with the supplied string. Use it to update a document you already have a handle for. This replaces the complete contents, so use Append when existing text must be retained.

Open the system file picker so the user can select one file. Check the result before reading from the selected document. Use it to import a file the user chooses without requiring a workspace path. Cancellation is a normal result, so only use the handle after checking it.

Open the system file picker with multiple selection enabled. Use it to import a batch of user-selected documents. Iterate the returned handles to read or inspect each file, and handle cancellation before starting the loop.

Ask the user to select a folder and return a handle for browsing or creating its children. Use it when the user should choose the location of an import or export. The handle provides access to that selected folder through Document methods.

Ask the user where to save the supplied contents, then return a handle to the saved file. Use it for an export where the user chooses the destination. Prepare the text or binary contents before opening the dialog.