pyui.select_save_file

Displays the system file-save dialog and returns a writable path handle to the file location the user names.

pyui.select_save_file(type, title, options)

Parameters

Parameter	Type	Description
type	table (optional)	An array of file-type filters, each a table {name = "Text File", filter = "*.txt"}. A filter may hold several patterns separated by semicolons, e.g. "*.jpg;*.jpeg". If omitted, any file name can be chosen.
title	string (optional)	The text shown in the title bar of the dialog.
options	table (optional)	Additional options, see below.

Options

Option	Type	Description
scope	string	"file" (the default): only the named file itself is writable. "folder": a second return value additionally grants write access to the containing folder and its direct files. "recursive": as "folder", including the complete sub-tree.
suggested_name	string	Pre-fills the file-name box of the dialog.
type_index	number	The 1-based index into type of the filter that is initially active. Defaults to the first entry.
allow_all	boolean	Appends an "All Files (*.*)" entry to the filter list. Defaults to true.
start_at	path handle	A path handle whose folder is pre-selected when the dialog opens.

Return values

Type	Description
path handle	A writable path handle to the chosen file location. The file does not need to exist yet. Returns nil if the user cancels the dialog.
path handle	(only when scope is "folder" or "recursive") A writable path handle to the containing folder with the corresponding access level.

Remarks:

If the user types a file name without an extension, the extension of the active filter is appended automatically. Overwriting an existing file is confirmed by the system dialog.

When scope is "folder" or "recursive", the user is asked to explicitly confirm write access to the folder. If the confirmation is declined, the function returns nil as though the dialog had been cancelled.

Example:

local file, folder = pyui.select_save_file({{name = "Wavefront OBJ", filter = "*.obj"}}, "Export mesh", {scope = "folder", suggested_name = "furniture"})
if file then
	pyio.write_lines(file, obj_lines)
	-- associated files (e.g. material libraries) can be written next to it through 'folder'
	pyio.write_lines(folder:append_path("furniture.mtl"), mtl_lines)
end

Version Support:

Minimum PYTHA Version: V26

See also:

pyui, Path Handles, pyui.select_open_file, pyui.select_folder, pyio.append_path