pyui.select_open_file

Displays the system file-open dialog and returns path handles to the existing files the user picks.

pyui.select_open_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, all files can be picked.
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 picked files themselves are accessible. "folder": a second return value additionally grants access to the containing folder and its direct files. "recursive": as "folder", including the complete sub-tree.
access	string	The access to request for the picked files. One of "read" (read only, the default) or "full" (modify the files in place).
allow_multiple	boolean	Allows picking more than one file. Defaults to false.
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
table	An array of path handles to the selected files (at least one entry), carrying the requested access. Returns nil if the user cancels the dialog.
path handle	(only when scope is "folder" or "recursive") A path handle to the containing folder with the corresponding access level.

Remarks:

On success, the first return value is always an array, also when allow_multiple is not set. The single picked file is then its only entry.

When access is "full" and 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 files, folder = pyui.select_open_file({{name = "Wavefront OBJ", filter = "*.obj"}}, "Import mesh", {scope = "folder"})
if files then
	local lines = pyio.parse_lines(files[1])
	-- referenced sibling files (e.g. material libraries) can be reached through 'folder'
	local mtl = folder:append_path("mesh.mtl")
end

Version Support:

Minimum PYTHA Version: V26

See also:

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