xtd::forms::application Class Reference

Inheritance diagram for xtd::forms::application:

Definition

Provides static methods and properties to manage an application, such as methods to start and stop an application, to process Windows messages, and methods to get information about an application. This class cannot be inherited.

Header

#include <xtd/forms/application>

Namespace

xtd::forms

Library

xtd.forms

Remarks

The application class has methods to start and stop applications and threads, and to process Windows messages, as follows:

• run() starts an application message loop on the current thread and, optionally, makes a form visible.
• exit() or exit_thread() stops a message loop.
• do_events() processes messages while your program is in a loop.
• add_message_filter() adds a message filter to the application message pump to monitor Windows messages.

You cannot create an instance of this class.

Examples

The following code example demonstrates the use of application class.

#include <xtd/xtd>
 
auto main() -> int {
  application::run(form {});
}

Examples

How to manage exception with application class.

#include <xtd/xtd>
 
class main_form : public form {
public:
  static auto main() {
    application::run(main_form());
  }
  
  main_form() {
    text("application and exception example");
    width(350);
    
    // Uncomment the following line to raise the exception in main entry point :
    //throw system_exception {};
 
    generate_handled_exception_button.auto_size(true);
    generate_handled_exception_button.location({10, 10});
    generate_handled_exception_button.parent(*this);
    generate_handled_exception_button.text("Generate handled exception");
    generate_handled_exception_button.click += event_handler {*this, &main_form::generate_handled_exception};
    
    generate_std_exception_button.auto_size(true);
    generate_std_exception_button.location({10, 50});
    generate_std_exception_button.parent(*this);
    generate_std_exception_button.text("Generate std exception");
    generate_std_exception_button.click += event_handler {*this, &main_form::generate_std_exception};
    
    generate_xtd_exception_button.auto_size(true);
    generate_xtd_exception_button.location({10, 90});
    generate_xtd_exception_button.parent(*this);
    generate_xtd_exception_button.text("Generate xtd exception");
    generate_xtd_exception_button.click += event_handler {*this, &main_form::generate_xtd_exception};
    
    generate_unknown_exception_button.auto_size(true);
    generate_unknown_exception_button.location({10, 130});
    generate_unknown_exception_button.parent(*this);
    generate_unknown_exception_button.text("Generate unknown exception");
    generate_unknown_exception_button.click += event_handler {*this, &main_form::generate_unknown_exception};
    
    consume_thread_exception_event_check_box.auto_size(true);
    consume_thread_exception_event_check_box.location({10, 170});
    consume_thread_exception_event_check_box.parent(*this);
    consume_thread_exception_event_check_box.text("Consume xtd::application::thread_exception event");
    consume_thread_exception_event_check_box.checked_changed += event_handler {*this, &main_form::consume_thread_exception_event};
  }
  
private:
  void consume_thread_exception_event() {
    if (consume_thread_exception_event_check_box.checked()) application::thread_exception += thread_exception_event_handler {*this, &main_form::on_thread_exception};
    else application::thread_exception -= thread_exception_event_handler {*this, &main_form::on_thread_exception};
  }
  
  void generate_handled_exception() {
    try {
      throw operation_canceled_exception {};
    } catch (const system_exception& e) {
      message_box::show(*this, e.message(), string::format("Exception {} handled", e.get_type().full_name()));
    }
  }
  void generate_std_exception() {throw std::invalid_argument("Invalid argument");}
  void generate_xtd_exception() {throw argument_out_of_range_exception {};}
  void generate_unknown_exception() {throw "Unknown exception occured";}
  
  void on_thread_exception(object& sender, const thread_exception_event_args& e) {
    diagnostics::debug::write_line(e.exception());
    application::exit();
  };
 
  button generate_handled_exception_button;
  button generate_std_exception_button;
  button generate_xtd_exception_button;
  button generate_unknown_exception_button;
  check_box consume_thread_exception_event_check_box;
};
 
startup_(main_form::main);

Public Static Events
static event< application, event_handler >	application_exit
	Occurs when the application is about to shut down.
static event< application, event_handler >	enter_thread_modal
	Occurs when the application is about to enter a modal state.
static event< application, event_handler >	idle
	Occurs when the application finishes processing and is about to enter the idle state.
static event< application, event_handler >	leave_thread_modal
	Occurs when the application is about to leave a modal state.
static event< application, threading::thread_exception_event_handler >	thread_exception
	Occurs when an untrapped thread exception is thrown.
static event< application, event_handler >	thread_exit
	Occurs when a thread is about to shut down. When the main thread for an application is about to be shut down, this event is raised first, followed by an application_exit event.

Public Static Properties
static auto	allow_quit () noexcept -> bool
	Gets a value indicating whether the caller can quit this application.
static auto	application_context () -> xtd::forms::application_context &
	Gets the application context associate to the application.
static auto	button_images () noexcept -> bool
	Gets button images are enabled.
static auto	button_images (bool value) -> void
	Gets button images are enabled.
static auto	common_app_data_path () noexcept -> xtd::string
	Gets the path for the application data that is shared among all users.
static auto	company_name () noexcept -> xtd::string
	Gets the company name associated with the application.
static auto	dark_mode () noexcept -> bool
	Gets a value indicating whether dark mode is enabled for the application.
static auto	dark_mode (bool value) -> void
	Sets a value indicating whether dark mode is enabled for the application.
static auto	executable_name () noexcept -> xtd::string
	Gets the executable name for the executable file that started the application, including the executable extension.
static auto	executable_path () noexcept -> xtd::string
	Gets the path for the executable file that started the application, including the executable name.
static auto	font_size_correction () -> bool
	Gets a value indicating whether font size correction is enabled.
static auto	font_size_correction (bool value) -> void
	Sets a value indicating whether font size correction is enabled.
static auto	light_mode () noexcept -> bool
	Gets a value indicating whether light mode is enabled for the application.
static auto	light_mode (bool value) -> void
	Sets a value indicating whether light mode is enabled for the application.
static auto	main_form () -> std::optional< form_ref >
	Gets the optional main form owned by the application.
static auto	menu_images () noexcept -> bool
	Gets menu images are enabled.
static auto	menu_images (bool value) -> void
	Sets menu images ilages are enabled.
static auto	message_loop () noexcept -> bool
	Gets a value indicating whether a message loop exists on this thread.
static auto	open_forms () noexcept -> const form_collection
	Gets a collection of open forms owned by the application.
static auto	product_name () noexcept -> xtd::string
	Gets the product name associated with this application.
static auto	product_version () noexcept -> xtd::string
	Gets the product version associated with this application.
static auto	startup_path () noexcept -> xtd::string
	Gets the path for the executable file that started the application, not including the executable name.
static auto	style_sheet () noexcept -> const xtd::forms::style_sheets::style_sheet &
	Gets current xtd::forms::style_sheets::style_sheet style sheet.
static auto	style_sheet (const xtd::forms::style_sheets::style_sheet &value) -> void
	Sets current xtd::forms::style_sheets::style_sheet style sheet.
static auto	style_sheets () noexcept -> const xtd::forms::style_sheets::style_sheet::style_sheets_t &
	Gets the installed xtd::forms::style_sheets::style_sheet style sheets.
static auto	style_sheet_names () noexcept -> const xtd::forms::style_sheets::style_sheet::style_sheet_names_t &
	Gets the installed xtd::forms::style_sheets::style_sheet style sheet names.
static auto	system_controls () noexcept -> bool
	Gets a value indicating whether the system control is enabled.
static auto	system_controls (bool value) -> void
	Sets a value indicating whether the system control is enabled.
static auto	system_font_size () noexcept -> bool
	Gets a value indicating whether the system font size is enabled.
static auto	system_font_size (bool value) -> void
	Sets a value indicating whether the system font size is enabled.
static auto	system_style_sheet () noexcept -> const xtd::forms::style_sheets::style_sheet &
	Gets system xtd::forms::style_sheets::style_sheet style sheet.
static auto	user_app_data_path () noexcept -> xtd::string
	Gets the path for the application data of a user.
static auto	use_wait_cursor () noexcept -> bool
	Gets whether the wait cursor is used for all open forms of the application.
static auto	use_wait_cursor (bool use_wait_cursor) -> void
	Sets whether the wait cursor is used for all open forms of the application.
static auto	visual_styles () noexcept -> bool
	Gets a value that indicates whether visual styles are enabled for the application.
static auto	visual_styles (bool value) -> void
	Sets a value that indicates whether visual styles are enabled for the application.

Public Static Methods
static auto	add_message_filter (const imessage_filter &value) -> void
	Adds a message filter to monitor Windows messages as they are routed to their destinations.
static auto	do_events () -> void
	Processes all Windows messages currently in the message queue.
static auto	enable_visual_styles () -> void
	Enables visual styles for the application.
static auto	exit () -> void
	Informs all message pumps that they must terminate, and then closes all application windows after the messages have been processed.
static auto	exit (cancel_event_args &e) -> void
	Informs all message pumps that they must terminate, and then closes all application windows after the messages have been processed.
static auto	exit_thread () -> void
	Exits the message loop on the current thread and closes all windows on the thread.
static auto	get_style_sheet_from_name (const xtd::string &name) -> xtd::forms::style_sheets::style_sheet
	Gets the installed xtd::forms::style_sheets::style_sheet style sheet from specified name.
static auto	raise_idle (const event_args &e) -> void
	Raises the Idle event.
static auto	register_message_loop_callback (message_loop_callback callback) -> void
	Registers a callback for checking whether the message loop is running in hosted environments.
static auto	remove_message_filter (const imessage_filter &value) -> void
	Removes a message filter from the message pump of the application.
static auto	restart () -> void
	Shuts down the application and starts a new instance immediately.
static auto	run () -> void
	Begins running a standard application message loop on the current thread, without a form.
static auto	run (xtd::forms::application_context &context) -> void
	Begins running a standard application message loop on the current thread, with an application_context.
static auto	run (const form &main_form) -> void
	Begins running a standard application message loop on the current thread, and makes the specified form visible.

Public Deprecated Static Properties
static auto	dark_mode_enabled () noexcept -> bool
	Return true if dark mode is enabled for the application; otherwise return false.
static auto	light_mode_enabled () noexcept -> bool
	Return true if dark mode is enabled for the application; otherwise return false.
static auto	use_visual_styles () noexcept -> bool
	Gets a value that indicates whether visual styles are enabled for the application.

PublicDeprecated Static Methods
static auto	enable_button_images () -> void
	Enables button images for the application.
static auto	enable_dark_mode () -> void
	Enables dark mode for the application.
static auto	enable_light_mode () -> void
	Enables light mode for the application.
static auto	enable_menu_images () -> void
	Enables menu images for the application.

Member Function Documentation

allow_quit()

auto xtd::forms::application::allow_quit ( ) -> bool

staticnodiscardnoexcept

Gets a value indicating whether the caller can quit this application.

Returns

true if the caller can quit this application; otherwise, false.

Remarks

This method returns false if it is called from a control being hosted within a Web browser. Thus, the control cannot quit the application.

application_context()

auto xtd::forms::application::application_context ( ) -> xtd::forms::application_context &

staticnodiscard

Gets the application context associate to the application.

Returns

An application context.

Remarks

The application context can be created by the user and sent to the application when the xtd::forms::application::run method is called.

button_images() [1/2]

auto xtd::forms::application::button_images ( ) -> bool

staticnodiscardnoexcept

Gets button images are enabled.

Returns

true if button images aree enabled; otherwise false.

Remarks

The default value is true.

This method has an effect only on linux.

button_images() [2/2]

auto xtd::forms::application::button_images ( bool value ) -> void

static

Gets button images are enabled.

Parameters

value

true if button images aree enabled; otherwise false.

Exceptions

xtd::invalid_operation_exception

If this method is called after xtd::forms::application::run.

Remarks

The default value is true.

This method has an effect only on linux.

common_app_data_path()

auto xtd::forms::application::common_app_data_path ( ) -> xtd::string

staticnodiscardnoexcept

Gets the path for the application data that is shared among all users.

Returns

The path for the application data that is shared among all users.

Remarks

If a path does not exist, one is created in the following format: base_path\company_name\product_name\product_version

product_version first looks to see if the assembly containing the main executable has the AssemblyInformationalVersion attribute on it. If this attribute exists, it is used for both product_version and common_app_data_path. If this attribute does not exist, both properties use the version of the executable file instead.

The path will be different depending on whether the Windows Forms application is deployed using ClickOnce. ClickOnce applications are stored in a per-user application cache in the C:\Documents and Settings\username directory. For more information, see Accessing Local and Remote Data in ClickOnce Applications.

company_name()

auto xtd::forms::application::company_name ( ) -> xtd::string

staticnodiscardnoexcept

Gets the company name associated with the application.

Returns

The company name.

Examples

The following code example gets this property and displays its value in a text box. The example requires that textBox1 has been placed on a form.

void PrintCompanyName() {
  textBox1.Text(xtd::string::format("The company name is: {0}", application::company_name);
}

dark_mode() [1/2]

auto xtd::forms::application::dark_mode ( ) -> bool

staticnodiscardnoexcept

Gets a value indicating whether dark mode is enabled for the application.

Returns

True is dark mode enabled; otherwise false.

dark_mode() [2/2]

auto xtd::forms::application::dark_mode ( bool value ) -> void

static

Sets a value indicating whether dark mode is enabled for the application.

Parameters

value

True is dark mode enabled; otherwise false.

Exceptions

xtd::invalid_operation_exception

If this method is called after xtd::forms::application::run.

executable_name()

auto xtd::forms::application::executable_name ( ) -> xtd::string

staticnodiscardnoexcept

Gets the executable name for the executable file that started the application, including the executable extension.

Returns

The executable name and executable name for the executable file that started the application.

executable_path()

auto xtd::forms::application::executable_path ( ) -> xtd::string

staticnodiscardnoexcept

Gets the path for the executable file that started the application, including the executable name.

Returns

The path and executable name for the executable file that started the application.

font_size_correction() [1/2]

auto xtd::forms::application::font_size_correction ( ) -> bool

staticnodiscard

Gets a value indicating whether font size correction is enabled.

Returns

true if font size correction is enabled; otherwise false.

Exceptions

xtd::invalid_operation_exception

If this method is called after xtd::forms::application::run.

Remarks

By default, xtd corrects the size of fonts on non-Windows operating systems so that they have the same aspect ratio as Windows.

If you disable this option, you will use the actual native font size of the operating system.

This method has an effect only on non Windows operating system.

font_size_correction() [2/2]

auto xtd::forms::application::font_size_correction ( bool value ) -> void

static

Sets a value indicating whether font size correction is enabled.

Parameters

value

true if font size correction is enabled; otherwise false.

Exceptions

xtd::invalid_operation_exception

If this method is called after xtd::forms::application::run.

Remarks

By default, xtd corrects the size of fonts on non-Windows operating systems so that they have the same aspect ratio as Windows.

If you disable this option, you will use the actual native font size of the operating system.

This method has an effect only on non Windows operating system.

light_mode() [1/2]

auto xtd::forms::application::light_mode ( ) -> bool

staticnodiscardnoexcept

Gets a value indicating whether light mode is enabled for the application.

Returns

True is light mode enabled; otherwise false.

light_mode() [2/2]

auto xtd::forms::application::light_mode ( bool value ) -> void

static

Sets a value indicating whether light mode is enabled for the application.

Parameters

value

True is light mode enabled; otherwise false.

Exceptions

xtd::invalid_operation_exception

If this method is called after xtd::forms::application::run.

main_form()

auto xtd::forms::application::main_form ( ) -> std::optional< form_ref >

staticnodiscard

Gets the optional main form owned by the application.

Returns

The optional main form.

Remarks

The return value doesn't necessarily contain the main form, as an application doesn't always have a main form. In fact, the xtd::forms::application method can be called with the xtd::forms::application_context class, which doesn't contain a main form.

menu_images() [1/2]

auto xtd::forms::application::menu_images ( ) -> bool

staticnodiscardnoexcept

Gets menu images are enabled.

Returns

true if menu images aree enabled; otherwise false.

Remarks

The default value is true.

This method has an effect only on linux.

menu_images() [2/2]

auto xtd::forms::application::menu_images ( bool value ) -> void

static

Sets menu images ilages are enabled.

Parameters

value

true if menu images aree enabled; otherwise false.

Exceptions

xtd::invalid_operation_exception

If this method is called after xtd::forms::application::run.

Remarks

The default value is true.

This method has an effect only on linux.

message_loop()

auto xtd::forms::application::message_loop ( ) -> bool

staticnodiscardnoexcept

Gets a value indicating whether a message loop exists on this thread.

Returns

true if a message loop exists; otherwise, false.

open_forms()

auto xtd::forms::application::open_forms ( ) -> const form_collection

staticnodiscardnoexcept

Gets a collection of open forms owned by the application.

Returns

A form_collection containing all the currently open forms owned by this application.

Remarks

The open_forms property represents a read-only collection of forms owned by the application.

product_name()

auto xtd::forms::application::product_name ( ) -> xtd::string

staticnodiscardnoexcept

Gets the product name associated with this application.

Returns

The product name.

product_version()

auto xtd::forms::application::product_version ( ) -> xtd::string

staticnodiscardnoexcept

Gets the product version associated with this application.

Returns

The product version.

startup_path()

auto xtd::forms::application::startup_path ( ) -> xtd::string

staticnodiscardnoexcept

Gets the path for the executable file that started the application, not including the executable name.

Returns

The path for the executable file that started the application.

style_sheet() [1/2]

auto xtd::forms::application::style_sheet ( ) -> const xtd::forms::style_sheets::style_sheet &

staticnodiscardnoexcept

Gets current xtd::forms::style_sheets::style_sheet style sheet.

Returns

The current xtd::forms::style_sheets::style_sheet style sheet.

Remarks

For more information, see Style sheets overview.

style_sheet() [2/2]

auto xtd::forms::application::style_sheet ( const xtd::forms::style_sheets::style_sheet & value ) -> void

static

Sets current xtd::forms::style_sheets::style_sheet style sheet.

Parameters

value

The current xtd::forms::style_sheets::style_sheet style sheet.

Remarks

For more information, see Style sheets overview.

style_sheets()

auto xtd::forms::application::style_sheets ( ) -> const xtd::forms::style_sheets::style_sheet::style_sheets_t &

staticnodiscardnoexcept

Gets the installed xtd::forms::style_sheets::style_sheet style sheets.

Returns

The installed xtd::forms::style_sheets::style_sheet style sheets.

Remarks

For more information, see Style sheets overview.

style_sheet_names()

auto xtd::forms::application::style_sheet_names ( ) -> const xtd::forms::style_sheets::style_sheet::style_sheet_names_t &

staticnodiscardnoexcept

Gets the installed xtd::forms::style_sheets::style_sheet style sheet names.

Returns

The installed xtd::forms::style_sheets::style_sheet names.

Remarks

For more information, see Style sheets overview.

system_controls() [1/2]

auto xtd::forms::application::system_controls ( ) -> bool

staticnodiscardnoexcept

Gets a value indicating whether the system control is enabled.

Returns

true if system control is enabled; otherwise false.

Remarks

By default, xtd uses the standard control (xtd::forms::control_appearance::standard) with this method you can change to force the use of system control (xtd::forms::control_appearance::system) instead.

The xtd::forms::control::control_appearance method can still be used to modify the control's appearance on the fly.

system_controls() [2/2]

auto xtd::forms::application::system_controls ( bool value ) -> void

static

Sets a value indicating whether the system control is enabled.

Parameters

value

true if system control is enabled; otherwise false.

Exceptions

xtd::invalid_operation_exception

If this method is called after xtd::forms::application::run.

Remarks

By default, xtd uses the standard control (xtd::forms::control_appearance::standard) with this method you can change to force the use of system control (xtd::forms::control_appearance::system) instead.

The xtd::forms::control::control_appearance method can still be used to modify the control's appearance on the fly.

system_font_size() [1/2]

auto xtd::forms::application::system_font_size ( ) -> bool

staticnodiscardnoexcept

Gets a value indicating whether the system font size is enabled.

Returns

true if the system font size is enabled; otherwise false.

Exceptions

xtd::invalid_operation_exception

If this method is called after xtd::forms::application::run.

Remarks

By default, xtd automatically limits the system font size to 9 points if it is larger than 9.

If you enable this option, you can use the actual font size of the system if it exceeds 9 points and at the same time the default sizes of the different controls will be adapted as well.

This method has an effect only on Gtk.

system_font_size() [2/2]

auto xtd::forms::application::system_font_size ( bool value ) -> void

static

Sets a value indicating whether the system font size is enabled.

Parameters

value

true if the system font size is enabled; otherwise false.

Exceptions

xtd::invalid_operation_exception

If this method is called after xtd::forms::application::run.

Remarks

By default, xtd automatically limits the system font size to 9 points if it is larger than 9.

If you enable this option, you can use the actual font size of the system if it exceeds 9 points and at the same time the default sizes of the different controls will be adapted as well.

This method has an effect only on Gtk.

system_style_sheet()

auto xtd::forms::application::system_style_sheet ( ) -> const xtd::forms::style_sheets::style_sheet &

staticnodiscardnoexcept

Gets system xtd::forms::style_sheets::style_sheet style sheet.

Returns

The system xtd::forms::style_sheets::style_sheet style sheet.

Remarks

The system style sheet is the style sheet corresponding to the current Operating System and the current Desktop Environment.

For more information, see Style sheets overview.

user_app_data_path()

auto xtd::forms::application::user_app_data_path ( ) -> xtd::string

staticnodiscardnoexcept

Gets the path for the application data of a user.

Returns

The path for the application data of a user.

Remarks

If a path does not exist, one is created in the following format: base_path\company_name\product_name\product_version

Data stored in this path is part of user profile that is enabled for roaming. A roaming user works on more than one computer in a network. The user profile for a roaming user is kept on a server on the network and is loaded onto a system when the user logs on. For a user profile to be considered for roaming, the operating system must support roaming profiles and it must be enabled.

A typical base path is "C:\Documents and Settings\username\Application Data".

use_wait_cursor() [1/2]

auto xtd::forms::application::use_wait_cursor ( ) -> bool

staticnodiscardnoexcept

Gets whether the wait cursor is used for all open forms of the application.

Returns

true is the wait cursor is used for all open forms; otherwise, false.

Remarks

When this property is set to true, the use_wait_cursor property of all open forms in the application will be set to true. This call will not return until this property has been set on all forms. Use this property when you have a long-running operation, and want to indicate in all application forms that the operation is still processing.

Examples

The following code example demonstrates the use of application use wait cursor property.

#include <xtd/xtd>
 
class form1 : public form {
public:
  form1() {
    text("Application use wait cursor example");
    
    button1.auto_size(true);
    button1.location({10, 10});
    button1.parent(*this);
    button1.text("Do something...");
    button1.click += delegate_ {
      application::use_wait_cursor(true);
      for (auto count = 0; count < 500; ++count) {
        application::do_events();
        thread::sleep(10_ms); // Simulate work...
      }
      application::use_wait_cursor(false);
    };
  }
  
private:
  button button1;
};
 
auto main() -> int {
  xtd::forms::application::run(form1 {});
}

use_wait_cursor() [2/2]

auto xtd::forms::application::use_wait_cursor ( bool use_wait_cursor ) -> void

static

Sets whether the wait cursor is used for all open forms of the application.

Parameters

use_wait_cursor

true is the wait cursor is used for all open forms; otherwise, false.

Remarks

When this property is set to true, the use_wait_cursor property of all open forms in the application will be set to true. This call will not return until this property has been set on all forms. Use this property when you have a long-running operation, and want to indicate in all application forms that the operation is still processing.

Examples

The following code example demonstrates the use of application use wait cursor property.

#include <xtd/xtd>
 
class form1 : public form {
public:
  form1() {
    text("Application use wait cursor example");
    
    button1.auto_size(true);
    button1.location({10, 10});
    button1.parent(*this);
    button1.text("Do something...");
    button1.click += delegate_ {
      application::use_wait_cursor(true);
      for (auto count = 0; count < 500; ++count) {
        application::do_events();
        thread::sleep(10_ms); // Simulate work...
      }
      application::use_wait_cursor(false);
    };
  }
  
private:
  button button1;
};
 
auto main() -> int {
  xtd::forms::application::run(form1 {});
}

visual_styles() [1/2]

auto xtd::forms::application::visual_styles ( ) -> bool

staticnodiscardnoexcept

Gets a value that indicates whether visual styles are enabled for the application.

Returns

true if visual styles are enabled; otherwise, false.

Remarks

This method enables visual styles for the application. Visual styles are the colors, fonts, and other visual elements that form an operating system theme. Controls will draw with visual styles if the control and the operating system support it. To have an effect, enable_visual_styles() must be called before creating any controls in the application; typically, enable_visual_styles() is the first line in the Main function. A separate manifest is not required to enable visual styles when calling enable_visual_styles().

This method has an effect only on Windows.

visual_styles() [2/2]

auto xtd::forms::application::visual_styles ( bool value ) -> void

static

Sets a value that indicates whether visual styles are enabled for the application.

Parameters

value

true if visual styles are enabled; otherwise, false.

Exceptions

xtd::invalid_operation_exception

If this method is called after xtd::forms::application::run.

Remarks

This method enables visual styles for the application. Visual styles are the colors, fonts, and other visual elements that form an operating system theme. Controls will draw with visual styles if the control and the operating system support it. To have an effect, enable_visual_styles() must be called before creating any controls in the application; typically, enable_visual_styles() is the first line in the Main function. A separate manifest is not required to enable visual styles when calling enable_visual_styles().

This method has an effect only on Windows.

add_message_filter()

auto xtd::forms::application::add_message_filter ( const imessage_filter & value ) -> void

static

Adds a message filter to monitor Windows messages as they are routed to their destinations.

Parameters

The	implementation of the imessage_filter interface you want to install.

Remarks

Use a message filter to prevent specific events from being raised or to perform special operations for an event before it is passed to an event handler. Message filters are unique to a specific thread.

Examples

application_add_message_filter.cpp.

do_events()

auto xtd::forms::application::do_events ( ) -> void

static

Processes all Windows messages currently in the message queue.

Remarks

When you run a Windows form, it creates the new form, which then waits for events to handle. Each time the form handles an event, it processes all the code associated with that event. All other events wait in the queue. While your code handles the event, your application does not respond. For example, the window does not repaint if another window is dragged on top.

If you call do_events in your code, your application can handle the other events. For example, if you have a form that adds data to a list_box and add do_events to your code, your form repaints when another window is dragged over it. If you remove do_events from your code, your form will not repaint until the click event handler of the button is finished executing.

Typically, you use this method in a loop to process messages.

Warning

Calling this method causes the current thread to be suspended while all waiting window messages are processed. If a message causes an event to be triggered, then other areas of your application code may execute. This can cause your application to exhibit unexpected behaviors that are difficult to debug. If you perform operations or computations that take a long time, it is often preferable to perform those operations on a new thread.

enable_visual_styles()

auto xtd::forms::application::enable_visual_styles ( ) -> void

static

Enables visual styles for the application.

Exceptions

xtd::invalid_operation_exception

If this method is called after xtd::forms::application::run.

Remarks

This method enables visual styles for the application. Visual styles are the colors, fonts, and other visual elements that form an operating system theme. Controls will draw with visual styles if the control and the operating system support it. To have an effect, enable_visual_styles() must be called before creating any controls in the application; typically, enable_visual_styles() is the first line in the Main function. A separate manifest is not required to enable visual styles when calling enable_visual_styles().

This method has an effect only on Windows.

exit() [1/2]

auto xtd::forms::application::exit ( ) -> void

static

Informs all message pumps that they must terminate, and then closes all application windows after the messages have been processed.

Remarks

The exit method stops all running message loops on all threads and closes all windows of the application. This method does not necessarily force the application to exit. The exit method is typically called from within a message loop, and forces Run to return. To exit a message loop for the current thread only, call exit_thread.

Exit raises the following events and performs the associated conditional actions:

• A form_closing event is raised for every form represented by the open_forms property. This event can be canceled by setting the cancel property of their form_closing_event_args parameter to true.
• If one of more of the handlers cancels the event, then exit returns without further action. Otherwise, a form_closed event is raised for every open form, then all running message loops and forms are closed.

exit() [2/2]

auto xtd::forms::application::exit ( cancel_event_args & e ) -> void

static

Informs all message pumps that they must terminate, and then closes all application windows after the messages have been processed.

Parameters

e	Returns whether any Form within the application cancelled the exit.

Remarks

The exit method stops all running message loops on all threads and closes all windows of the application. This method does not necessarily force the application to exit. The exit method is typically called from within a message loop, and forces Run to return. To exit a message loop for the current thread only, call exit_thread.

Exit raises the following events and performs the associated conditional actions:

• A form_closing event is raised for every form represented by the open_forms property. This event can be canceled by setting the cancel property of their form_closing_event_args parameter to true.
• If one of more of the handlers cancels the event, then exit returns without further action. Otherwise, a form_closed event is raised for every open form, then all running message loops and forms are closed.

exit_thread()

auto xtd::forms::application::exit_thread ( ) -> void

static

Exits the message loop on the current thread and closes all windows on the thread.

Remarks

Use this method to exit the message loop of the current thread. This method causes the call to run for the current thread to return. To exit the entire application, call exit.

get_style_sheet_from_name()

auto xtd::forms::application::get_style_sheet_from_name ( const xtd::string & name ) -> xtd::forms::style_sheets::style_sheet

staticnodiscard

Gets the installed xtd::forms::style_sheets::style_sheet style sheet from specified name.

Returns

The xtd::forms::style_sheets::style_sheet style sheet from name.

Exceptions

xtd::argument_exception

The style sheet name not tvalid.

Remarks

Use xtd::forms::style_sheets::style_sheet::style_sheet_names to retreive valid style sheet names.

For more information, see Style sheets overview.

raise_idle()

auto xtd::forms::application::raise_idle ( const event_args & e ) -> void

static

Raises the Idle event.

Parameters

e	The event_args objects to pass to the idle event.

register_message_loop_callback()

auto xtd::forms::application::register_message_loop_callback ( message_loop_callback callback ) -> void

static

Registers a callback for checking whether the message loop is running in hosted environments.

Parameters

callback

The method to call when Windows Forms needs to check if the hosting environment is still sending messages.

Remarks

This method is used when hosting Windows Forms in another environment. In hosted environments, the message_loop property will always return false if Windows Forms is not processing messages. Use this callback to tell Windows Forms if the hosting environment is still processing messages.

remove_message_filter()

auto xtd::forms::application::remove_message_filter ( const imessage_filter & value ) -> void

static

Removes a message filter from the message pump of the application.

Parameters

value

The implementation of the imessage_filter to remove from the application.

Remarks

You can remove a message filter when you no longer want to capture Windows messages before they are dispatched.

restart()

auto xtd::forms::application::restart ( ) -> void

static

Shuts down the application and starts a new instance immediately.

Remarks

Applications are restarted in the context in which they were initially run.

If your application was originally supplied command-line options when it first executed, restart will launch the application again with the same options.

Examples

The following code example demonstrates the use of application restart method.

#include <xtd/xtd>
 
auto main() -> int {
  auto restart_count = environment::get_environment_variable("application_restart_count").empty() ? 0 : parse<int>(environment::get_environment_variable("application_restart_count"));
  auto main_form = form::create(string::format("Restart {} times", restart_count));
  auto restart_button = button::create(main_form, "Restart", {10, 10});
  restart_button.click += application::restart;
  
  environment::set_environment_variable("application_restart_count", int32_object {restart_count + 1}.to_string());
  
  application::run(main_form);
}

run() [1/3]

auto xtd::forms::application::run ( ) -> void

static

Begins running a standard application message loop on the current thread, without a form.

Remarks

In a Win32-based or Windows Forms application, a message loop is a routine in code that processes user events, such as mouse clicks and keyboard strokes. Every running Windows-based application requires an active message loop, called the main message loop. When the main message loop is closed, the application exits. In Windows Forms, this loop is closed when the exit method is called, or when the exit_thread method is called on the thread that is running the main message loop.

Most Windows Forms developers will not need to use this version of the method. You should use the run(const form&) overload to start an application with a main form, so that the application terminates when the main form is closed. For all other situations, use the run(application_context&) overload, which supports supplying an application_context object for better control over the lifetime of the application.

Examples

The following code example demonstrates the use of application run method.

#include <xtd/xtd>
 
auto main() -> int {
  application::run();
}

Examples

about_dialog_from_executing_assembly_informations.cpp, application_use_wait_cursor.cpp, busy_box.cpp, busy_dialog.cpp, control_with_name_operator.cpp, form2.cpp, horizontal_layout_panel.cpp, process_form.cpp, screen_informations.cpp, trace_message_box.cpp, tutorial_application_icon.cpp, tutorial_button.cpp, tutorial_communicate.cpp, tutorial_simple_application.cpp, and vertical_layout_panel.cpp.

run() [2/3]

auto xtd::forms::application::run ( xtd::forms::application_context & context ) -> void

static

Begins running a standard application message loop on the current thread, with an application_context.

Parameters

context

An ApplicationContext in which the application is run.

Remarks

The message loop runs until xtd::forms::application::exit or xtd::forms::application::exit_thread is called or the xtd::forms::application_context::thread_exit event is raised on the context object.

Examples

The following code example demonstrates the use of application run method.

#include <xtd/xtd>
 
auto main() -> int {
  auto context = application_context {};
  
  auto form1 = form::create("Form 1 (Click the client area to set form as the main form)");
  form1.click += delegate_ {context.main_form(form1);};
  form1.show();
  
  auto form2 = form::create("Form 2 (Click the client area to set form as the main form)");
  form2.click += delegate_ {context.main_form(form2);};
  form2.show();
  
  auto form3 = form::create("Form 3 (Click the client area to set form as the main form)");
  form3.click += delegate_ {context.main_form(form3);};
  form3.show();
  
  // if no client area form clicked, the application will not exit when you close the forms.
  application::run(context);
}

run() [3/3]

auto xtd::forms::application::run ( const form & main_form ) -> void

static

Begins running a standard application message loop on the current thread, and makes the specified form visible.

Parameters

main_form

A form that represents the form to make visible.

Remarks

Typically, the main function of an application calls this method and passes to it the main window of the application.

This method adds an event handler to the main_form parameter for the closed event. The event handler calls xtd::forms::application::exit_thread to clean up the application.

Examples

The following code example demonstrates the use of application run method.

#include <xtd/xtd>
 
auto main() -> int {
  application::run(form {});
}

dark_mode_enabled()

auto xtd::forms::application::dark_mode_enabled ( ) -> bool

staticnodiscardnoexcept

Return true if dark mode is enabled for the application; otherwise return false.

Returns

True is dark mode enabled; otherwise false.

Deprecated

Replaced by xtd::application::dark_mode - Will be removed in version 1.2.0.

light_mode_enabled()

auto xtd::forms::application::light_mode_enabled ( ) -> bool

staticnodiscardnoexcept

Return true if dark mode is enabled for the application; otherwise return false.

Returns

True is light mode enabled; otherwise false.

Deprecated

Replaced by xtd::application::light_mode - Will be removed in version 1.2.0.

use_visual_styles()

auto xtd::forms::application::use_visual_styles ( ) -> bool

staticnodiscardnoexcept

Gets a value that indicates whether visual styles are enabled for the application.

Returns

true if visual styles are enabled; otherwise, false.

Remarks

The visual styles can be enabled by calling enable_xtd::forms::application::visual_styles.

Deprecated

Replaced by xtd::application::visual_styles - Will be removed in version 1.2.0.

enable_button_images()

auto xtd::forms::application::enable_button_images ( ) -> void

static

Enables button images for the application.

Exceptions

xtd::invalid_operation_exception

If this method is called after xtd::forms::application::run.

Remarks

This method has an effect only on linux.

Deprecated

Replaced by xtd::application::button_images - Will be removed in version 1.2.0.

enable_dark_mode()

auto xtd::forms::application::enable_dark_mode ( ) -> void

static

Enables dark mode for the application.

Exceptions

xtd::invalid_operation_exception

If this method is called after xtd::forms::application::run.

Remarks

By default, the dark mode is enabled automatically if the system is in dark mode.

xtd::forms::application::enable_dark_mode sets the application in dark mode even if your system is in light mode.

Deprecated

Replaced by xtd::application::dark_mode - Will be removed in version 1.2.0.

enable_light_mode()

auto xtd::forms::application::enable_light_mode ( ) -> void

static

Enables light mode for the application.

Exceptions

xtd::invalid_operation_exception

If this method is called after xtd::forms::application::run.

Remarks

By default, the light mode is enabled automatically if the system is in light mode.

xtd::forms::application::enable_light_mode sets the application in light mode even if your system is in dark mode.

Deprecated

Replaced by xtd::application::light_mode - Will be removed in version 1.2.0.

enable_menu_images()

auto xtd::forms::application::enable_menu_images ( ) -> void

static

Enables menu images for the application.

Exceptions

xtd::invalid_operation_exception

If this method is called after xtd::forms::application::run.

Remarks

This method has an effect only on linux.

Deprecated

Replaced by xtd::application::menu_images - Will be removed in version 1.2.0.

Member Data Documentation

application_exit

event<application, event_handler> xtd::forms::application::application_exit

static

Occurs when the application is about to shut down.

Remarks

You must attach the event handlers to the application_exit event to perform unhandled, required tasks before the application stops running. You can close files opened by this application, or dispose of objects that garbage collection did not reclaim.

For more information about handling events, see Handling and Raising Events.

enter_thread_modal

event<application, event_handler> xtd::forms::application::enter_thread_modal

static

Occurs when the application is about to enter a modal state.

Remarks

For more information about handling events, see Handling and Raising Events.

idle

event<application, event_handler> xtd::forms::application::idle

static

Occurs when the application finishes processing and is about to enter the idle state.

Remarks

If you have tasks that you must perform before the thread becomes idle, attach them to this event.

For more information about handling events, see Handling and Raising Events.

Examples

The following code example demonstrates the use of application idle event.

#include <xtd/xtd>
 
namespace application_idle_example {
  class form1 : public form {
  public:
    form1() {
      application::idle += {self_, &form1::on_application_idle};
    }
    
  private:
    void on_application_idle(object sender, const event_args& e) {
      text(string::format("{}", ++counter));
    }
    
    int counter = 0;
  };
}
 
auto main() -> int {
  application::run(application_idle_example::form1 {});
}

leave_thread_modal

event<application, event_handler> xtd::forms::application::leave_thread_modal

static

Occurs when the application is about to leave a modal state.

Remarks

For more information about handling events, see Handling and Raising Events.

thread_exception

event<application, threading::thread_exception_event_handler> xtd::forms::application::thread_exception

static

Occurs when an untrapped thread exception is thrown.

Remarks

This event allows your Windows Forms application to handle otherwise unhandled exceptions that occur in Windows Forms threads. Attach your event handlers to the thread_exception event to deal with these exceptions, which will leave your application in an unknown state. Where possible, exceptions should be handled by a structured exception handling block.

You can change whether this callback is used for unhandled Windows Forms thread exceptions by setting set_unhandled_exception_mode. To catch exceptions that occur in threads not created and owned by Windows Forms, use the unhandled_exception event handler.

Note

To guarantee that no activations of this event are missed, you must attach a handler before you call application::run.

Remarks

For more information about handling events, see Handling and Raising Events.

Examples

The following exemple shows how to use xtd::application::thread_exception event.

#include <xtd/xtd>
 
class main_form : public form {
public:
  static auto main() {
    application::thread_exception += thread_exception_event_handler {&main_form::on_thread_exception};
    application::run(main_form());
  }
  
  main_form() {
    text("application::thread_exception event example");
    
    generate_exception_button.auto_size(true);
    generate_exception_button.click += delegate_ {throw argument_out_of_range_exception {};};
  }
  
private:
  static void on_thread_exception(object& sender, const thread_exception_event_args& e) {
    auto result = show_thread_exception_dialog("Fatal Windows Forms Error", e.exception());
    if (result == forms::dialog_result::abort) application::exit();
  };
  
  static forms::dialog_result show_thread_exception_dialog(const string& title, const std::exception& e) {
    auto error_msg = "An application error occurred. Please contact the adminstrator with the following information:\n\n"_s;
    if (is<exception>(e)) error_msg = error_msg + as<exception>(e).message() + (is<exception>(e) ? "\n\nStack Trace:\n" + as<exception>(e).stack_trace() : "");
    else error_msg = error_msg + e.what();
    return message_box::show(error_msg, title, message_box_buttons::abort_retry_ignore, message_box_icon::stop);
  }
 
  button generate_exception_button = button::create(self_, "Generate exception", {10, 10});
};
 
startup_(main_form::main);

thread_exit

event<application, event_handler> xtd::forms::application::thread_exit

static

Occurs when a thread is about to shut down. When the main thread for an application is about to be shut down, this event is raised first, followed by an application_exit event.

Remarks

You must attach the event handlers to the thread_exit event to perform any unhandled, required tasks before the thread stops running. Close files opened by this thread, or dispose of objects that the garbage collector did not reclaim.

For more information about handling events, see Handling and Raising Events.

---

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

• xtd.forms/include/xtd/forms/application.hpp