xtd.forms - Reference Guide  0.1.0
Modern c++17 library containing classes for creating Windows-based applications that take full advantage of the rich user interface features available in the Microsoft Windows, Apple macOS and Linux like Ubuntu operating system.
xtd::forms::file_dialog Class Referenceabstract

Displays a dialog box from which the user can select a file. More...

#include <file_dialog.hpp>

Inheritance diagram for xtd::forms::file_dialog:
xtd::forms::common_dialog xtd::forms::component xtd::forms::open_file_dialog xtd::forms::save_file_dialog

Public Member Functions

 file_dialog ()=default
 Initializes a new instance of the common_dialog class. More...
 
virtual bool add_extension () const
 Gets a value indicating whether the dialog box automatically adds an extension to a file name if the user omits the extension. More...
 
virtual file_dialogadd_extension (bool value)
 Sets a value indicating whether the dialog box automatically adds an extension to a file name if the user omits the extension. More...
 
virtual bool auto_upgrade_enabled () const
 Gets a value indicating whether this file_dialog instance should automatically upgrade appearance and behavior when running on Windows Vista. More...
 
virtual file_dialogauto_upgrade_enabled (bool value)
 Sets a value indicating whether this file_dialog instance should automatically upgrade appearance and behavior when running on Windows Vista. More...
 
virtual bool check_file_exists () const
 Gets a value indicating whether the dialog box displays a warning if the user specifies a file name that does not exist. More...
 
virtual file_dialogcheck_file_exists (bool value)
 Sets a value indicating whether the dialog box displays a warning if the user specifies a file name that does not exist. More...
 
virtual bool check_path_exists () const
 
virtual file_dialogcheck_path_exists (bool value)
 
virtual const ustringdefault_ext () const
 
virtual file_dialogdefault_ext (const ustring &value)
 
virtual bool dereference_link () const
 
virtual file_dialogdereference_link (bool value)
 
virtual const ustringfile_name () const
 
virtual file_dialogfile_name (const ustring &value)
 
virtual const std::vector< ustringfile_names () const
 
virtual const ustringfilter () const
 
virtual file_dialogfilter (const ustring &value)
 
virtual size_t filter_index () const
 
virtual file_dialogfilter_index (size_t value)
 
virtual const ustringinitial_directory () const
 
virtual file_dialoginitial_directory (const ustring &value)
 
virtual bool multi_select () const
 
virtual file_dialogmulti_select (bool value)
 
size_t options () const
 
void reset () override
 Resets all properties to their default values. More...
 
virtual bool restore_directory () const
 
virtual file_dialogrestore_directory (bool value)
 
bool run_dialog (intptr_t hwnd_owner) override
 When overridden in a derived class, specifies a common dialog box. More...
 
virtual bool show_help () const
 
virtual file_dialogshow_help (bool value)
 
virtual bool show_hidden_files () const
 
virtual file_dialogshow_hidden_files (bool value)
 
virtual bool show_preview () const
 
virtual file_dialogshow_preview (bool value)
 
virtual bool support_multi_dotted_extensions () const
 
virtual file_dialogsupport_multi_dotted_extensions (bool value)
 
virtual const ustringtitle () const
 
virtual file_dialogtitle (const ustring &value)
 
ustring to_string () const
 
virtual bool validate_names () const
 
virtual file_dialogvalidate_names (bool value)
 
- Public Member Functions inherited from xtd::forms::common_dialog
 common_dialog ()=default
 Initializes a new instance of the common_dialog class. More...
 
xtd::forms::dialog_result show_dialog ()
 Runs a common dialog box with a default owner. More...
 
xtd::forms::dialog_result show_dialog (const iwin32_window &owner)
 Runs a common dialog box with the specified owner. More...
 
std::any tag () const
 Gets an object that contains data about the control. More...
 
common_dialogtag (const std::any &tag)
 Sets an object that contains data about the control. More...
 

Friends

class open_file_dialog
 
class save_file_dialog
 

Additional Inherited Members

- Public Attributes inherited from xtd::forms::common_dialog
event< common_dialog, help_event_handler< component & > > help_request
 Occurs when the user clicks the Help button on a common dialog box. More...
 
- Protected Member Functions inherited from xtd::forms::common_dialog
virtual void on_help_request (help_event_args &e)
 Raises the help_request event. More...
 
- Protected Member Functions inherited from xtd::forms::component
virtual bool can_raise_events () const
 Gets a value indicating whether the component can raise an event. More...
 
bool design_mode () const
 Gets a value that indicates whether the component is currently in design mode. More...
 

Detailed Description

Displays a dialog box from which the user can select a file.

Remarks
file_dialog is an abstract class that contains common behavior for the open_file_dialog and save_file_dialog classes. It is not intended to be used directly but contains common behavior for those two classes. You cannot create an instance of file_dialog. Although the class is declared public, you cannot inherit from it, as it contains private abstract methods. To create a dialog box to select or save a file, use open_file_dialog or save_file_dialog.
file_dialog is a modal dialog box; therefore, when shown, it blocks the rest of the application until the user has chosen a file. When a dialog box is displayed modally, no input (keyboard or mouse click) can occur except to objects on the dialog box. The program must hide or close the dialog box (usually in response to some user action) before input to the calling program can occur.
Warning
When you use classes derived from file_dialog, such as open_file_dialog and save_file_dialog, avoid using string literals containing absolute paths. Instead, dynamically obtain the path using one or more of the techniques described in the following table.
Remarks
If you want to enable users to select a folder instead of a file, use the folder_browser_dialog.
Depending upon the type of application, how data associated with the application is stored, and the reason for accessing the file system, there are many possible ways in which you can create a directory path. The following table shows the techniques for creating paths dynamically.
Path or program category Class and members to use
Standard Windows paths, such as Program Files, MyDocuments, the Desktop and so on The xtd::environment class is the most complete source for these, either through its static methods, such as system_directory, or through the get_folder_path method, using one of the environment::special_folder enumerated values.
Paths related to the current application The application class has static members to obtain certain paths, such as startup_path, executable_path, local_user_app_data_path, and common_app_data_path.

The get_temp_path method of the xtd::io::path returns the path of the temporary folder.

The get_current_directory method of the xtd::io::directory class returns the application's current executing directory.

The root_directory property of the drive_info class represents the specified drive's root directory.
Paths stored as application settings Access the corresponding applications settings property of the wrapper class derived from application_settings_base. For more information, see application settings for Windows Forms.
Registry storage Some applications store directory information in the registry. The Application class has the common_ app_data_path and local_user_app_data_path properties that resolve to a registry_key value.
ClickOnce applications For click_once applications, use application class members such as user_app_data_path, which will return a pointer to the click_once data directory. For more information, see accessing local and remote data in click_once applications.
International applications For international applications, retrieve the relative path portion from a string resource in your application by using the xtd::resources::resource_reader class. For more information about globalization and localization
Notice that a full path may be built up using one or more of the described techniques. For example, the get_folder_path method might be used to obtain the path to the MyDocuments folder, then an application setting may be used to add a relative subdirectory portion.
The xtd::io::path class contains static members to assist in manipulating absolute and relative path strings, whereas the System.IO.File and xtd::io::directory classes have static members that actually manipulate files and directories, respectively.
Important
If the user of your application changes the folder in the file_dialog, then the current working directory for your application is set to the location specified in the file_dialog. To prevent this, set the restore_directory property to true.

Constructor & Destructor Documentation

§ file_dialog()

xtd::forms::file_dialog::file_dialog ( )
default

Initializes a new instance of the common_dialog class.

Member Function Documentation

§ add_extension() [1/2]

virtual bool xtd::forms::file_dialog::add_extension ( ) const
inlinevirtual

Gets a value indicating whether the dialog box automatically adds an extension to a file name if the user omits the extension.

Returns
true if the dialog box adds an extension to a file name if the user omits the extension; otherwise, false. The default value is true.

§ add_extension() [2/2]

virtual file_dialog& xtd::forms::file_dialog::add_extension ( bool  value)
inlinevirtual

Sets a value indicating whether the dialog box automatically adds an extension to a file name if the user omits the extension.

Parameters
valuetrue if the dialog box adds an extension to a file name if the user omits the extension; otherwise, false. The default value is true.

§ auto_upgrade_enabled() [1/2]

virtual bool xtd::forms::file_dialog::auto_upgrade_enabled ( ) const
inlinevirtual

Gets a value indicating whether this file_dialog instance should automatically upgrade appearance and behavior when running on Windows Vista.

Returns
true if this file_dialog instance should automatically upgrade appearance and behavior when running on Windows Vista; otherwise, false. The default is true.
Remarks
If this property is false, the file_dialog class will have a Windows XP-style appearance and behavior on Windows Vista.
On Windows XP, this property does not have any effect.

§ auto_upgrade_enabled() [2/2]

virtual file_dialog& xtd::forms::file_dialog::auto_upgrade_enabled ( bool  value)
inlinevirtual

Sets a value indicating whether this file_dialog instance should automatically upgrade appearance and behavior when running on Windows Vista.

Parameters
valuetrue if this file_dialog instance should automatically upgrade appearance and behavior when running on Windows Vista; otherwise, false. The default is true.
Remarks
If this property is false, the file_dialog class will have a Windows XP-style appearance and behavior on Windows Vista.
On Windows XP, this property does not have any effect.

§ check_file_exists() [1/2]

virtual bool xtd::forms::file_dialog::check_file_exists ( ) const
inlinevirtual

Gets a value indicating whether the dialog box displays a warning if the user specifies a file name that does not exist.

Returns
true if the dialog box displays a warning if the user specifies a file name that does not exist; otherwise, false. The default value is false.
Remarks
The default value is true for an inheriting open_file_dialog and false for an inheriting save_file_dialog.

§ check_file_exists() [2/2]

virtual file_dialog& xtd::forms::file_dialog::check_file_exists ( bool  value)
inlinevirtual

Sets a value indicating whether the dialog box displays a warning if the user specifies a file name that does not exist.

Parameters
valuetrue if the dialog box displays a warning if the user specifies a file name that does not exist; otherwise, false. The default value is false.
Remarks
The default value is true for an inheriting open_file_dialog and false for an inheriting save_file_dialog.

§ options()

size_t xtd::forms::file_dialog::options ( ) const
inline
Returns
Gets values to initialize the file_dialog.
A bitwise combination of internal values that initializes the file_dialog.
The options property corresponds to the flags used to initialize a color dialog box using Win32. Use the properties of the file_dialog class to get and set the options.

§ reset()

void xtd::forms::file_dialog::reset ( )
overridevirtual

Resets all properties to their default values.

Remarks
When overriding reset() in a derived class, be sure to call the base class's reset() method.

Implements xtd::forms::common_dialog.

§ run_dialog()

bool xtd::forms::file_dialog::run_dialog ( intptr_t  hwnd_owner)
overridevirtual

When overridden in a derived class, specifies a common dialog box.

Parameters
hwnd_ownerA value that represents the window handle of the owner window for the common dialog box.
Returns
true if the dialog box was successfully run; otherwise, false.

Implements xtd::forms::common_dialog.


The documentation for this class was generated from the following file: