xtd - Reference Guide  0.2.0
Modern c++17/20 framework to create console, GUI and unit test applications on Windows, macOS, Linux, iOS and android.
Public Member Functions | Protected Member Functions | List of all members
xtd::forms::folder_browser_dialog Class Referencefinal

#include <folder_browser_dialog.h>

Definition

Prompts the user to select a folder. This class cannot be inherited.

Namespace
xtd::forms
Library
xtd.forms
Examples
The following code example demonstrate the use of folder_browser_dialog dialog.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
using namespace xtd::forms;
class form1 : public form {
public:
form1() {
text("Folder browser dialog example");
controls().push_back(button1);
button1.location({10, 10});
button1.text("Folder...");
button1.click += [&] {
label1.text(ustring::format("Path = {}", selected_path));
}
};
label1.parent(*this);
label1.text("Path = ");
label1.auto_size(true);
label1.location({10, 40});
}
private:
label label1;
};
int main() {
application::run(form1());
}
Examples:
folder_browser_dialog.cpp.

Public Member Functions

 folder_browser_dialog ()=default
 Initializes a new instance of the folder_browser_dialog class. More...
 
bool auto_upgrade_enable () const
 Gets a value that indicates whether the dialog will be automatically upgraded to enable new features. More...
 
folder_browser_dialogauto_upgrade_enable (bool value)
 Sets a value that indicates whether the dialog will be automatically upgraded to enable new features. More...
 
const xtd::ustringdescription () const
 Gets the descriptive text displayed above the tree view control in the dialog box. More...
 
folder_browser_dialogdescription (const xtd::ustring &value)
 Sets the descriptive text displayed above the tree view control in the dialog box. More...
 
void reset () override
 Resets all options to their default values, the last selected color to black, and the custom colors to their default values. More...
 
environment::special_folder root_folder () const
 Gets the root folder where the browsing starts from. More...
 
folder_browser_dialogroot_folder (environment::special_folder value)
 Sets the root folder where the browsing starts from. More...
 
const xtd::ustringselected_path () const
 Gets the path selected by the user. More...
 
folder_browser_dialogselected_path (const xtd::ustring &value)
 Sets the path selected by the user. More...
 
bool show_new_folder_button () const
 Gets a value indicating whether the New Folder button appears in the folder browser dialog box. More...
 
folder_browser_dialogshow_new_folder_button (bool value)
 Sets a value indicating whether the New Folder button appears in the folder browser dialog box. More...
 
- 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 dialog_result () const
 Get async dialog_result result after dialog box is closing. 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...
 
void show_sheet (const iwin32_window &owner)
 Runs a common dialog box with the specified owner. More...
 
xtd::forms::dialog_result show_sheet_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...
 
- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object. More...
 
virtual bool equals (const object &obj) const noexcept
 Determines whether the specified object is equal to the current object. More...
 
virtual size_t get_hash_code () const noexcept
 Serves as a hash function for a particular type. More...
 
template<typename object_t >
std::unique_ptr< object_t > memberwise_clone () const
 Gets the type of the current instance. More...
 
virtual xtd::ustring to_string () const noexcept
 Returns a std::string that represents the current object. More...
 

Protected Member Functions

bool run_dialog (intptr_t owner) override
 When overridden in a derived class, specifies a common dialog box. More...
 
void run_sheet (intptr_t owner) override
 When overridden in a derived class, specifies a common dialog box. More...
 
- Protected Member Functions inherited from xtd::forms::common_dialog
virtual void on_dialog_closed (const dialog_closed_event_args &e)
 Raises the common_dialog::dialog_close event. More...
 
virtual void on_help_request (help_event_args &e)
 Raises the common_dialog::help_request event. More...
 
- Protected Member Functions inherited from xtd::forms::component
 component ()=default
 Initialises a new instance of the component class. More...
 
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...
 

Additional Inherited Members

- Public Attributes inherited from xtd::forms::common_dialog
event< common_dialog, dialog_closed_event_handlerdialog_closed
 Occurs when the user close a common dialog box with dialog close button or other dialog buttons. More...
 
event< common_dialog, help_event_handlerhelp_request
 Occurs when the user clicks the Help button on a common dialog box. More...
 
- Static Public Member Functions inherited from xtd::object
static bool equals (const object &object_a, const object &object_b) noexcept
 Determines whether the specified object instances are considered equal. More...
 
static bool reference_equals (const object &object_a, const object &object_b) noexcept
 Determines whether the specified object instances are the same instance. More...
 

Constructor & Destructor Documentation

◆ folder_browser_dialog()

xtd::forms::folder_browser_dialog::folder_browser_dialog ( )
default

Initializes a new instance of the folder_browser_dialog class.

Remarks
The parameterless constructor initializes properties to their default values.
When a new folder_browser_dialog is created, the root_folder property is set to xtd::environment::special_folder::desktop, the description property is set to an empty string (""), the selected_path property is set to an empty string, and the show_new_folder_button property is set to true.
Typically, after creating a new folder_browser_dialog, you set the root_folder to the location from which to start browsing. Optionally, you can set the selected_path to the path of a subfolder of root_folder that will initially be selected. You can also optionally set the description property to provide additional instructions to the user. Finally, call the show_dialog or show_sheet or show_sheet_dialog method to display the dialog box to the user. When the dialog box is closed and the dialog result from show_dialog is dialog_result::ok, the selected_path will be a string containing the path to the selected folder.
folder_browser_dialog is a modal dialog box; therefore, when shown, it blocks the rest of the application until the user has chosen a folder. 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.

Member Function Documentation

◆ auto_upgrade_enable() [1/2]

bool xtd::forms::folder_browser_dialog::auto_upgrade_enable ( ) const
inline

Gets a value that indicates whether the dialog will be automatically upgraded to enable new features.

Returns
true if the the dialog will be automatically upgraded to enable new features; otherwise, false. The default value is true.

◆ auto_upgrade_enable() [2/2]

folder_browser_dialog& xtd::forms::folder_browser_dialog::auto_upgrade_enable ( bool  value)
inline

Sets a value that indicates whether the dialog will be automatically upgraded to enable new features.

Parameters
valuetrue if the the dialog will be automatically upgraded to enable new features; otherwise, false. The default value is true.
Returns
Current folder_browser_dialog.

◆ description() [1/2]

const xtd::ustring& xtd::forms::folder_browser_dialog::description ( ) const
inline

Gets the descriptive text displayed above the tree view control in the dialog box.

Returns
The description to display. The default is an empty string ("").
Remarks
The description property can be used to specify additional information to the user, like instructions.

◆ description() [2/2]

folder_browser_dialog& xtd::forms::folder_browser_dialog::description ( const xtd::ustring value)
inline

Sets the descriptive text displayed above the tree view control in the dialog box.

Parameters
valueThe description to display. The default is an empty string ("").
Returns
Current folder_browser_dialog.
Remarks
The description property can be used to specify additional information to the user, like instructions.

◆ reset()

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

Resets all options to their default values, the last selected color to black, and the custom colors to their default values.

Implements xtd::forms::common_dialog.

◆ root_folder() [1/2]

environment::special_folder xtd::forms::folder_browser_dialog::root_folder ( ) const
inline

Gets the root folder where the browsing starts from.

Returns
One of the environment::special_folder values. The default is environment::special_folder::desktop.
Remarks
Only the specified folder and any subfolders that are beneath it will appear in the dialog box and be selectable. The selected_path property, along with root_folder, determines what the selected folder will be when the dialog box is displayed, as long as SelectedPath is an absolute path that is a subfolder of root_folder (or more accurately, points to a subfolder of the shell namespace represented by root_folder).

◆ root_folder() [2/2]

folder_browser_dialog& xtd::forms::folder_browser_dialog::root_folder ( environment::special_folder  value)
inline

Sets the root folder where the browsing starts from.

Parameters
valueOne of the environment::special_folder values. The default is environment::special_folder::desktop.
Returns
Current folder_browser_dialog.
Remarks
Only the specified folder and any subfolders that are beneath it will appear in the dialog box and be selectable. The selected_path property, along with root_folder, determines what the selected folder will be when the dialog box is displayed, as long as SelectedPath is an absolute path that is a subfolder of root_folder (or more accurately, points to a subfolder of the shell namespace represented by root_folder).

◆ run_dialog()

bool xtd::forms::folder_browser_dialog::run_dialog ( intptr_t  owner)
overrideprotectedvirtual

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

Parameters
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.

◆ run_sheet()

void xtd::forms::folder_browser_dialog::run_sheet ( intptr_t  owner)
overrideprotectedvirtual

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

Parameters
ownerA value that represents the window handle of the owner window for the common dialog box.

Implements xtd::forms::common_dialog.

◆ selected_path() [1/2]

const xtd::ustring& xtd::forms::folder_browser_dialog::selected_path ( ) const
inline

Gets the path selected by the user.

Returns
The path of the folder first selected in the dialog box or the last folder selected by the user. The default is an empty string ("").
Remarks
If the selected_ath property is set before showing the dialog box, the folder with this path will be the selected folder, as long as selected_path is set to an absolute path that is a subfolder of root_folder (or more accurately, points to a subfolder of the shell namespace represented by root_folder).
If the show_dialog returns OK, meaning the user clicked the OK button, the selected_path property will return a string containing the path to the selected folder. If show_dialog returns Cancel, meaning the user canceled out of the dialog box, this property will have the same value that it had prior to displaying the dialog box. If the user selects a folder that does not have a physical path (for example, My Computer), the OK button on the dialog box will be disabled.
Examples:
folder_browser_dialog.cpp.

◆ selected_path() [2/2]

folder_browser_dialog& xtd::forms::folder_browser_dialog::selected_path ( const xtd::ustring value)
inline

Sets the path selected by the user.

Parameters
valueThe path of the folder first selected in the dialog box or the last folder selected by the user. The default is an empty string ("").
Returns
Current folder_browser_dialog.
Remarks
If the selected_ath property is set before showing the dialog box, the folder with this path will be the selected folder, as long as selected_path is set to an absolute path that is a subfolder of root_folder (or more accurately, points to a subfolder of the shell namespace represented by root_folder).
If the show_dialog returns OK, meaning the user clicked the OK button, the selected_path property will return a string containing the path to the selected folder. If show_dialog returns Cancel, meaning the user canceled out of the dialog box, this property will have the same value that it had prior to displaying the dialog box. If the user selects a folder that does not have a physical path (for example, My Computer), the OK button on the dialog box will be disabled.

◆ show_new_folder_button() [1/2]

bool xtd::forms::folder_browser_dialog::show_new_folder_button ( ) const
inline

Gets a value indicating whether the New Folder button appears in the folder browser dialog box.

Returns
true if the New Folder button is shown in the dialog box; otherwise, false. The default is true.
Remarks
When show_new_folder_button is true, the New Folder button is visible, giving the user a chance to create a folder. When the user clicks the New Folder button, a new folder is created and the user is prompted to specify the folder name. The selected node in the tree becomes the parent of the new folder. The actual caption of the New Folder button can vary depending upon the operating system

◆ show_new_folder_button() [2/2]

folder_browser_dialog& xtd::forms::folder_browser_dialog::show_new_folder_button ( bool  value)
inline

Sets a value indicating whether the New Folder button appears in the folder browser dialog box.

Parameters
valuetrue if the New Folder button is shown in the dialog box; otherwise, false. The default is true.
Remarks
When show_new_folder_button is true, the New Folder button is visible, giving the user a chance to create a folder. When the user clicks the New Folder button, a new folder is created and the user is prompted to specify the folder name. The selected node in the tree becomes the parent of the new folder. The actual caption of the New Folder button can vary depending upon the operating system

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