API reference - Class FileDialog

Notation used in Ruby API documentation

Description: Various methods to request a file name

This class provides some basic dialogs to select a file or directory. This functionality is provided through the static (class) methods ask_...

Here are some examples:

# get an existing directory:
v = RBA::FileDialog::ask_existing_dir("Dialog Title", ".")
# get multiple files:
v = RBA::FileDialog::ask_open_file_names("Title", ".", "All files (*)")
# ask for one file name to save a file:
v = RBA::FileDialog::ask_save_file_name("Title", ".", "All files (*)")

All these examples return the "nil" value if "Cancel" is pressed.

If you have enabled the Qt binding, you can use QFileDialog directly.

Public constructors

FileDialognewCreates a new object of this class

Public methods

[const]voidassign(const FileDialog other)Assign the contents of another object to self
voidcreateEnsures the C++ object is created
voiddestroyExplicitly destroy the object
[const]booldestroyed?Returns a value indicating whether the object was already destroyed
[const]FileDialogdupCreates a copy of self
[const]boolis_const_object?Returns a value indicating whether the reference is a const reference

Public static methods and constants

variantask_existing_dir(string title,
string dir)
Open a dialog to select a directory
variantask_open_file_name(string title,
string dir,
string filter)
Select one file for opening
variantask_open_file_names(string title,
string dir,
string filter)
Select one or multiple files for opening
variantask_save_file_name(string title,
string dir,
string filter)
Select one file for writing

Deprecated methods (protected, public, static, non-static and constructors)

[static]StringValueget_existing_dir(string title,
string dir)
Use of this method is deprecated
[static]StringValueget_open_file_name(string title,
string dir,
string filter)
Use of this method is deprecated
[static]StringListValueget_open_file_names(string title,
string dir,
string filter)
Use of this method is deprecated
[static]StringValueget_save_file_name(string title,
string dir,
string filter)
Use of this method is deprecated

Detailed description

[static] variant ask_existing_dir(string title,string dir)

Description: Open a dialog to select a directory

title:The title of the dialog
dir:The directory selected initially
Returns:The directory path selected or "nil" if "Cancel" was pressed

This method has been introduced in version 0.23. It is somewhat easier to use than the get_... equivalent.

[static] variant ask_open_file_name(string title,string dir,string filter)

Description: Select one file for opening

title:The title of the dialog
dir:The directory selected initially
filter:The filters available, for example "Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)"
Returns:The path of the file selected or "nil" if "Cancel" was pressed

This method has been introduced in version 0.23. It is somewhat easier to use than the get_... equivalent.

[static] variant ask_open_file_names(string title,string dir,string filter)

Description: Select one or multiple files for opening

title:The title of the dialog
dir:The directory selected initially
filter:The filters available, for example "Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)"
Returns:An array with the file paths selected or "nil" if "Cancel" was pressed

This method has been introduced in version 0.23. It is somewhat easier to use than the get_... equivalent.

[static] variant ask_save_file_name(string title,string dir,string filter)

Description: Select one file for writing

title:The title of the dialog
dir:The directory selected initially
filter:The filters available, for example "Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)"
Returns:The path of the file chosen or "nil" if "Cancel" was pressed

This method has been introduced in version 0.23. It is somewhat easier to use than the get_... equivalent.

[const] void assign(const FileDialog other)

Description: Assign the contents of another object to self

This method assigns the contents of another object to self. This is a deep copy that does not only copy the reference but the actual content.

void create

Description: Ensures the C++ object is created

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

void destroy

Description: Explicitly destroy the object

Explicitly destroy the object on C++ side if it was owned by the Ruby interpreter. Subsequent access to this object will throw an exception. If the object is not owned by Ruby, this method will do nothing.

[const] bool destroyed?

Description: Returns a value indicating whether the object was already destroyed

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

[const] FileDialog dup

Description: Creates a copy of self

[static] StringValue get_existing_dir(string title,string dir)

Description: Open a dialog to select a directory

title:The title of the dialog
dir:The directory selected initially
Returns:A StringValue object that contains the directory path selected or with has_value? = false if "Cancel" was pressed

This method is deprecated.

[static] StringValue get_open_file_name(string title,string dir,string filter)

Description: Select one file for opening

title:The title of the dialog
dir:The directory selected initially
filter:The filters available, for example "Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)"
Returns:A StringValue object that contains the files selected or with has_value? = false if "Cancel" was pressed

This method is deprecated.

[static] StringListValue get_open_file_names(string title,string dir,string filter)

Description: Select one or multiple files for opening

title:The title of the dialog
dir:The directory selected initially
filter:The filters available, for example "Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)"
Returns:A StringListValue object that contains the files selected or with has_value? = false if "Cancel" was pressed

This method is deprecated.

[static] StringValue get_save_file_name(string title,string dir,string filter)

Description: Select one file for writing

title:The title of the dialog
dir:The directory selected initially
filter:The filters available, for example "Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)"
Returns:A StringValue object that contains the files selected or with has_value? = false if "Cancel" was pressed

This method is deprecated.

[const] bool is_const_object?

Description: Returns a value indicating whether the reference is a const reference

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

[static] FileDialog new

Description: Creates a new object of this class