xtd::forms::folder_browser_dialog Class Reference

Inheritance diagram for xtd::forms::folder_browser_dialog:

Definition

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

Header

#include <xtd/forms/folder_browser_dialog>

Namespace

xtd::forms

Library

xtd.forms

Appearance

	Windows	macOS	Gnome
Light
Dark

Examples

The following code example demonstrates the use of folder_browser_dialog dialog.

#include <xtd/xtd>
 
class form1 : public form {
public:
  form1() {
    text("Folder browser dialog example");
    controls().add(button1);
    auto_scroll(true);
    
    button1.location({10, 10});
    button1.text("Folder...");
    button1.click += delegate_ {
      auto dialog = folder_browser_dialog {};
      dialog.selected_path(selected_path);
      if (dialog.show_sheet_dialog(*this) == forms::dialog_result::ok) {
        selected_path = dialog.selected_path();
        label1.text(string::format("Path = {}", selected_path));
      }
    };
    
    label1.parent(*this);
    label1.text("Path = ");
    label1.auto_size(true);
    label1.location({10, 50});
  }
  
private:
  button button1;
  label label1;
  string selected_path;
};
 
auto main() -> int {
  application::run(form1 {});
}

Public Constructors
	folder_browser_dialog ()
	Initializes a new instance of the folder_browser_dialog class.

Public Properties
auto	auto_upgrade_enable () const noexcept -> bool
	Gets a value that indicates whether the dialog will be automatically upgraded to enable new features.
auto	auto_upgrade_enable (bool value) -> folder_browser_dialog &
	Sets a value that indicates whether the dialog will be automatically upgraded to enable new features.
auto	description () const noexcept -> const xtd::string &
	Gets the descriptive text displayed above the tree view control in the dialog box.
auto	description (const xtd::string &value) -> folder_browser_dialog &
	Sets the descriptive text displayed above the tree view control in the dialog box.
auto	root_folder () const noexcept -> xtd::environment::special_folder
	Gets the root folder where the browsing starts from.
auto	root_folder (xtd::environment::special_folder value) -> folder_browser_dialog &
	Sets the root folder where the browsing starts from.
auto	selected_path () const noexcept -> const xtd::string &
	Gets the path selected by the user.
auto	selected_path (const xtd::string &value) -> folder_browser_dialog &
	Sets the path selected by the user.
bool	show_new_folder_button () const noexcept
	Gets a value indicating whether the New Folder button appears in the folder browser dialog box.
auto	show_new_folder_button (bool value) -> folder_browser_dialog &
	Sets a value indicating whether the New Folder button appears in the folder browser dialog box.

Public Methods
auto	reset () noexcept -> void override
	Resets all options to their default values, the last selected color to black, and the custom colors to their default values.

Protected Methods
auto	run_dialog (xtd::intptr owner) -> bool override
	When overridden in a derived class, specifies a common dialog box.
auto	run_sheet (xtd::intptr owner) -> void override
	When overridden in a derived class, specifies a common dialog box.

Additional Inherited Members
xtd::event< common_dialog, xtd::forms::help_event_handler >	help_request
	Occurs when the user clicks the Help button on a common dialog box.
xtd::event< common_dialog, xtd::forms::dialog_closed_event_handler >	dialog_closed
	Occurs when the user close a common dialog box with dialog close button or other dialog buttons.
	common_dialog ()
	Initializes a new instance of the common_dialog class.
auto	dialog_result () const noexcept -> xtd::forms::dialog_result
	Gets async dialog_result result after dialog box is closing.
auto	tag () const noexcept -> const xtd::any_object &
	Gets an object that contains data about the control.
auto	tag (const xtd::any_object &value) -> common_dialog &
	Sets an object that contains data about the control.
auto	show_dialog () -> xtd::forms::dialog_result
	Runs a common dialog box with a default owner.
auto	show_dialog (const iwin32_window &owner) -> xtd::forms::dialog_result
	Runs a common dialog box with the specified owner.
auto	show_sheet (const iwin32_window &owner) -> void
	Runs a common dialog box with the specified owner.
auto	show_sheet_dialog (const iwin32_window &owner) -> xtd::forms::dialog_result
	Runs a common dialog box with the specified owner.
	object ()=default
	Create a new instance of the ultimate base class object.
virtual auto	equals (const object &obj) const noexcept -> bool
	Determines whether the specified object is equal to the current object.
virtual auto	get_hash_code () const noexcept -> xtd::usize
	Serves as a hash function for a particular type.
virtual auto	get_type () const noexcept -> type_object
	Gets the type of the current instance.
template<typename object_t>
auto	memberwise_clone () const -> xtd::unique_ptr_object< object_t >
	Creates a shallow copy of the current object.
virtual auto	to_string () const -> xtd::string
	Returns a xtd::string that represents the current object.
template<typename object_a_t, typename object_b_t>
static auto	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept -> bool
	Determines whether the specified object instances are considered equal.
template<typename object_a_t, typename object_b_t>
static auto	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept -> bool
	Determines whether the specified object instances are the same instance.
virtual auto	on_dialog_closed (const xtd::forms::dialog_closed_event_args &e) -> void
	Raises the common_dialog::dialog_close event.
virtual auto	on_help_request (xtd::forms::help_event_args &e) -> void
	Raises the common_dialog::help_request event.
auto	set_dialog_result (xtd::forms::dialog_result value) -> void
	Sets async dialog_result result after dialog box is closing.
	component ()
	Initialises a new instance of the component class.
virtual auto	can_raise_events () const noexcept -> bool
	Gets a value indicating whether the component can raise an event.
auto	design_mode () const noexcept -> bool
	Gets a value that indicates whether the component is currently in design mode.

Constructor & Destructor Documentation

folder_browser_dialog()

xtd::forms::folder_browser_dialog::folder_browser_dialog

(

)

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]

auto xtd::forms::folder_browser_dialog::auto_upgrade_enable ( ) const -> bool

nodiscardnoexcept

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]

auto xtd::forms::folder_browser_dialog::auto_upgrade_enable

(

bool

value

)

-> folder_browser_dialog &

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

Parameters

value

true 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]

auto xtd::forms::folder_browser_dialog::description ( ) const -> const xtd::string &

nodiscardnoexcept

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]

auto xtd::forms::folder_browser_dialog::description

(

const xtd::string &

value

)

-> folder_browser_dialog &

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

Parameters

value

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

root_folder() [1/2]

auto xtd::forms::folder_browser_dialog::root_folder ( ) const -> xtd::environment::special_folder

nodiscardnoexcept

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]

auto xtd::forms::folder_browser_dialog::root_folder

(

xtd::environment::special_folder

value

)

-> folder_browser_dialog &

Sets the root folder where the browsing starts from.

Parameters

value

One 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).

selected_path() [1/2]

auto xtd::forms::folder_browser_dialog::selected_path ( ) const -> const xtd::string &

nodiscardnoexcept

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.

selected_path() [2/2]

auto xtd::forms::folder_browser_dialog::selected_path

(

const xtd::string &

value

)

-> folder_browser_dialog &

Sets the path selected by the user.

Parameters

value

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 ("").

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

nodiscardnoexcept

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]

auto xtd::forms::folder_browser_dialog::show_new_folder_button

(

bool

value

)

-> folder_browser_dialog &

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

Parameters

value

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

reset()

auto xtd::forms::folder_browser_dialog::reset ( ) -> void

overridevirtualnoexcept

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.

run_dialog()

auto xtd::forms::folder_browser_dialog::run_dialog ( xtd::intptr owner ) -> bool

overrideprotectedvirtual

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

Parameters

owner

A 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()

auto xtd::forms::folder_browser_dialog::run_sheet ( xtd::intptr owner ) -> void

overrideprotectedvirtual

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

Parameters

owner

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

Implements xtd::forms::common_dialog.

---

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

• xtd.forms/include/xtd/forms/folder_browser_dialog.hpp