xtd 0.2.0
Loading...
Searching...
No Matches
xtd::forms::application Class Referencefinal
Inheritance diagram for xtd::forms::application:
xtd::static_object

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/forms/application>
#include <xtd/forms/form>
auto main() -> int {
}
static void run()
Begins running a standard application message loop on the current thread, without a form.
Represents a window or dialog box that makes up an application's user interface.
Definition form.h:52
Examples
How to manage exception with application class.
#include <xtd/forms/application>
#include <xtd/forms/button>
#include <xtd/forms/form>
#include <xtd/forms/message_box>
#include <xtd/operation_canceled_exception>
#include <xtd/startup>
#include <stdexcept>
using namespace std;
using namespace xtd;
using namespace xtd::forms;
class main_form : public form {
public:
static auto main() {
}
text("application and exception example");
// Uncomment the following line to raise the exception in main entry point :
//throw system_exception(current_stack_frame_);
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_exception_button.auto_size(true);
generate_exception_button.location({10, 50});
generate_exception_button.parent(*this);
generate_exception_button.text("Generate exception");
generate_exception_button.click += event_handler(*this, &main_form::generate_exception);
generate_system_exception_button.auto_size(true);
generate_system_exception_button.location({10, 90});
generate_system_exception_button.parent(*this);
generate_system_exception_button.text("Generate system exception");
generate_system_exception_button.click += event_handler(*this, &main_form::generate_system_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);
}
private:
void generate_handled_exception() {
try {
} catch (const xtd::system_exception& e) {
message_box::show(*this, e.message(), ustring::format("Exception {} handled", e.name()));
}
}
void generate_exception() {throw invalid_argument("Invalid argument");}
void generate_system_exception() {throw argument_out_of_range_exception(current_stack_frame_);}
void generate_unknown_exception() {throw "Unknown exception occured";}
button generate_handled_exception_button;
button generate_exception_button;
button generate_system_exception_button;
button generate_unknown_exception_button;
};
startup_(main_form::main);
The exception that is thrown when one of the arguments provided to a method is out of range.
Definition argument_out_of_range_exception.h:20
static std::optional< form_ref > main_form()
Gets the optional main form owned by the application.
Represents a Windows button control.
Definition button.h:47
static dialog_result show()
Displays a message box.
The exception that is thrown in a thread upon cancellation of an operation that the thread was execut...
Definition operation_canceled_exception.h:18
Defines the base class for predefined exceptions in the xtd namespace.
Definition system_exception.h:24
generic_event_handler<> event_handler
Represents the method that will handle an event that has no event data.
Definition event_handler.h:32
static ustring format(const ustring &fmt, args_t &&... args)
Writes the text representation of the specified arguments list, to string using the specified format ...
Definition ustring.h:1131
#define startup_(main_method)
Defines the entry point to be called when the application loads. Generally this is set either to the ...
Definition startup.h:167
#define current_stack_frame_
Provides information about the current stack frame.
Definition current_stack_frame.h:16
@ invalid_argument
Invalid argument.
@ e
The E key.
@ text
The xtd::forms::status_bar_panel displays text in the standard font.
The xtd::forms namespace contains classes for creating Windows-based applications that take full adva...
Definition xtd_about_box.h:12
The xtd namespace contains all fundamental classes to access Hardware, Os, System,...
Definition xtd_about_box.h:10

Public Static Events

static event< application, delegate< void(const event_args &)> > application_exit
 Occurs when the application is about to shut down.
 
static event< application, delegate< void(const event_args &)> > enter_thread_modal
 Occurs when the application is about to enter a modal state.
 
static event< application, delegate< void(const event_args &)> > idle
 Occurs when the application finishes processing and is about to enter the idle state.
 
static event< application, delegate< void(const event_args &)> > leave_thread_modal
 Occurs when the application is about to leave a modal state.
 
static event< application, delegate< void(const event_args &)> > 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 bool allow_quit () noexcept
 Gets a value indicating whether the caller can quit this application.
 
static xtd::forms::application_contextapplication_context ()
 Gets the application context associate to the application.
 
static bool button_images () noexcept
 Gets button images are enabled.
 
static void button_images (bool value)
 Gets button images are enabled.
 
static xtd::ustring common_app_data_path () noexcept
 Gets the path for the application data that is shared among all users.
 
static xtd::ustring company_name () noexcept
 Gets the company name associated with the application.
 
static bool dark_mode () noexcept
 Gets a value indicating whether dark mode is enabled for the application.
 
static void dark_mode (bool value)
 Sets a value indicating whether dark mode is enabled for the application.
 
static bool dark_mode_enabled () noexcept
 Return true if dark mode is enabled for the application; otherwise return false.
 
static xtd::ustring executable_name () noexcept
 Gets the executable name for the executable file that started the application, including the executable extension.
 
static xtd::ustring executable_path () noexcept
 Gets the path for the executable file that started the application, including the executable name.
 
static bool font_size_correction ()
 Gets a value indicating whether font size correction is enabled.
 
static void font_size_correction (bool value)
 Sets a value indicating whether font size correction is enabled.
 
static bool keep_cloned_controls () noexcept
 Gets a value indicating whether the xtd framework keep cloned control is enabled.
 
static void keep_cloned_controls (bool value)
 Sets a value indicating whether the xtd framework keep cloned control is enabled.
 
static bool light_mode () noexcept
 Gets a value indicating whether light mode is enabled for the application.
 
static void light_mode (bool value)
 Sets a value indicating whether light mode is enabled for the application.
 
static bool light_mode_enabled () noexcept
 Return true if dark mode is enabled for the application; otherwise return false.
 
static std::optional< form_refmain_form ()
 Gets the optional main form owned by the application.
 
static bool menu_images () noexcept
 Gets menu images are enabled.
 
static void menu_images (bool value)
 Sets menu images ilages are enabled.
 
static bool message_loop () noexcept
 Gets a value indicating whether a message loop exists on this thread.
 
static const form_collection open_forms () noexcept
 Gets a collection of open forms owned by the application.
 
static xtd::ustring product_name () noexcept
 Gets the product name associated with this application.
 
static xtd::ustring product_version () noexcept
 Gets the product version associated with this application.
 
static xtd::ustring startup_path () noexcept
 Gets the path for the executable file that started the application, not including the executable name.
 
static const xtd::forms::style_sheets::style_sheetstyle_sheet () noexcept
 Gets current xtd::forms::style_sheets::style_sheet style sheet.
 
static void style_sheet (const xtd::forms::style_sheets::style_sheet &value)
 Sets current xtd::forms::style_sheets::style_sheet style sheet.
 
static const xtd::forms::style_sheets::style_sheet::style_sheets_tstyle_sheets () noexcept
 Gets the installed xtd::forms::style_sheets::style_sheet style sheets.
 
static const xtd::forms::style_sheets::style_sheet::style_sheet_names_tstyle_sheet_names () noexcept
 Gets the installed xtd::forms::style_sheets::style_sheet style sheet names.
 
static bool system_controls () noexcept
 Gets a value indicating whether the system control is enabled.
 
static void system_controls (bool value)
 Sets a value indicating whether the system control is enabled.
 
static bool system_font_size () noexcept
 Gets a value indicating whether the system font size is enabled.
 
static void system_font_size (bool value)
 Sets a value indicating whether the system font size is enabled.
 
static const xtd::forms::style_sheets::style_sheetsystem_style_sheet () noexcept
 Gets system xtd::forms::style_sheets::style_sheet style sheet.
 
static xtd::ustring user_app_data_path () noexcept
 Gets the path for the application data of a user.
 
static bool use_visual_styles () noexcept
 Gets a value that indicates whether visual styles are enabled for the application.
 
static bool use_wait_cursor () noexcept
 Gets whether the wait cursor is used for all open forms of the application.
 
static void use_wait_cursor (bool use_wait_cursor)
 Sets whether the wait cursor is used for all open forms of the application.
 
static bool visual_styles () noexcept
 Gets a value that indicates whether visual styles are enabled for the application.
 
static void visual_styles (bool value)
 Sets a value that indicates whether visual styles are enabled for the application.
 

Public Static Methods

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

Member Function Documentation

◆ add_message_filter()

static void xtd::forms::application::add_message_filter ( const imessage_filter value)
static

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

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

◆ allow_quit()

static bool xtd::forms::application::allow_quit ( )
staticnoexcept

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

static xtd::forms::application_context & xtd::forms::application::application_context ( )
static

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]

static bool xtd::forms::application::button_images ( )
staticnoexcept

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]

static void xtd::forms::application::button_images ( bool  value)
static

Gets button images are enabled.

Parameters
valuetrue if button images aree enabled; otherwise false.
Exceptions
xtd::invalid_operation_exceptionIf 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()

static xtd::ustring xtd::forms::application::common_app_data_path ( )
staticnoexcept

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

static xtd::ustring xtd::forms::application::company_name ( )
staticnoexcept

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::ustring::format("The company name is: {0}", application::company_name);
}
static xtd::ustring company_name() noexcept
Gets the company name associated with the application.

◆ dark_mode() [1/2]

static bool xtd::forms::application::dark_mode ( )
staticnoexcept

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

Returns
True is dark mode enabled; otherwise false.

◆ dark_mode() [2/2]

static void xtd::forms::application::dark_mode ( bool  value)
static

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

Parameters
valueTrue is dark mode enabled; otherwise false.
Exceptions
xtd::invalid_operation_exceptionIf this method is called after xtd::forms::application::run.

◆ dark_mode_enabled()

static bool xtd::forms::application::dark_mode_enabled ( )
staticnoexcept

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 0.4.0

◆ do_events()

static void xtd::forms::application::do_events ( )
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_button_images()

static void xtd::forms::application::enable_button_images ( )
static

Enables button images for the application.

Exceptions
xtd::invalid_operation_exceptionIf 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 0.4.0

◆ enable_dark_mode()

static void xtd::forms::application::enable_dark_mode ( )
static

Enables dark mode for the application.

Exceptions
xtd::invalid_operation_exceptionIf 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 0.4.0

◆ enable_light_mode()

static void xtd::forms::application::enable_light_mode ( )
static

Enables light mode for the application.

Exceptions
xtd::invalid_operation_exceptionIf 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 0.4.0

◆ enable_menu_images()

static void xtd::forms::application::enable_menu_images ( )
static

Enables menu images for the application.

Exceptions
xtd::invalid_operation_exceptionIf 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 0.4.0

◆ enable_visual_styles()

static void xtd::forms::application::enable_visual_styles ( )
static

Enables visual styles for the application.

Exceptions
xtd::invalid_operation_exceptionIf 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.

◆ executable_name()

static xtd::ustring xtd::forms::application::executable_name ( )
staticnoexcept

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

static xtd::ustring xtd::forms::application::executable_path ( )
staticnoexcept

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.

◆ exit() [1/2]

static void xtd::forms::application::exit ( )
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]

static void xtd::forms::application::exit ( cancel_event_args e)
static

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

Parameters
eReturns 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()

static void xtd::forms::application::exit_thread ( )
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.

◆ font_size_correction() [1/2]

static bool xtd::forms::application::font_size_correction ( )
static

Gets a value indicating whether font size correction is enabled.

Returns
true if font size correction is enabled; otherwise false.
Exceptions
xtd::invalid_operation_exceptionIf 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]

static void xtd::forms::application::font_size_correction ( bool  value)
static

Sets a value indicating whether font size correction is enabled.

Parameters
valuetrue if font size correction is enabled; otherwise false.
Exceptions
xtd::invalid_operation_exceptionIf 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.

◆ get_style_sheet_from_name()

static xtd::forms::style_sheets::style_sheet xtd::forms::application::get_style_sheet_from_name ( const xtd::ustring name)
static

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

◆ keep_cloned_controls() [1/2]

static bool xtd::forms::application::keep_cloned_controls ( )
staticnoexcept

Gets a value indicating whether the xtd framework keep cloned control is enabled.

Returns
true if xtd framework keep cloned control is enabled; otherwise false.
Remarks
By default the value is false.

◆ keep_cloned_controls() [2/2]

static void xtd::forms::application::keep_cloned_controls ( bool  value)
static

Sets a value indicating whether the xtd framework keep cloned control is enabled.

Parameters
valuetrue if xtd framework keep cloned control is enabled; otherwise false.
Exceptions
xtd::invalid_operation_exceptionIf this method is called after xtd::forms::application::run.
Remarks
By default the value is false.

◆ light_mode() [1/2]

static bool xtd::forms::application::light_mode ( )
staticnoexcept

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

Returns
True is light mode enabled; otherwise false.

◆ light_mode() [2/2]

static void xtd::forms::application::light_mode ( bool  value)
static

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

Parameters
valueTrue is light mode enabled; otherwise false.
Exceptions
xtd::invalid_operation_exceptionIf this method is called after xtd::forms::application::run.

◆ light_mode_enabled()

static bool xtd::forms::application::light_mode_enabled ( )
staticnoexcept

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 0.4.0

◆ main_form()

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

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]

static bool xtd::forms::application::menu_images ( )
staticnoexcept

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]

static void xtd::forms::application::menu_images ( bool  value)
static

Sets menu images ilages are enabled.

Parameters
valuetrue if menu images aree enabled; otherwise false.
Exceptions
xtd::invalid_operation_exceptionIf 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()

static bool xtd::forms::application::message_loop ( )
staticnoexcept

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

Returns
true if a message loop exists; otherwise, false.

◆ open_forms()

static const form_collection xtd::forms::application::open_forms ( )
staticnoexcept

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

static xtd::ustring xtd::forms::application::product_name ( )
staticnoexcept

Gets the product name associated with this application.

Returns
The product name.

◆ product_version()

static xtd::ustring xtd::forms::application::product_version ( )
staticnoexcept

Gets the product version associated with this application.

Returns
The product version.

◆ raise_idle()

static void xtd::forms::application::raise_idle ( const event_args e)
static

Raises the Idle event.

Parameters
eThe event_args objects to pass to the idle event.

◆ register_message_loop_callback()

static void xtd::forms::application::register_message_loop_callback ( message_loop_callback  callback)
static

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

Parameters
callbackThe 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()

static void xtd::forms::application::remove_message_filter ( const imessage_filter value)
static

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

Parameters
valueThe 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()

static void xtd::forms::application::restart ( )
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/forms/application>
#include <xtd/forms/button>
#include <xtd/forms/form>
#include <xtd/environment>
using namespace std;
using namespace xtd;
using namespace xtd::forms;
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(ustring::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", to_string(restart_count + 1));
}
static void set_environment_variable(const xtd::ustring &variable, const xtd::ustring &value)
Creates, modifies, or deletes an environment variable stored in the current process.
static xtd::ustring get_environment_variable(const xtd::ustring &variable)
Retrieves the value of an environment variable from the current process.
static void restart()
Shuts down the application and starts a new instance immediately.
static button create()
A factory to create an xtd::forms::button.
event< control, event_handler > click
Occurs when the xtd::forms::control is clicked.
Definition control.h:1479
static form create()
A factory to create an xtd::forms::form.
int parse< int >(const std::string &str, number_styles styles)
Convert a string into a type.
Definition parse.h:137
std::string to_string(const date_time &value, const std::string &fmt, const std::locale &loc)
Convert a specified value into a string with specified format and locale.
Definition date_time.h:1080

◆ run() [1/3]

static void xtd::forms::application::run ( )
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/forms/application>
using namespace xtd::forms;
auto main() -> int {
}
Examples
application.cpp, application_add_message_filter.cpp, application_use_wait_cursor.cpp, busy_box.cpp, busy_dialog.cpp, button2.cpp, button3.cpp, button4.cpp, control_with_name_operator.cpp, form2.cpp, hello_world_cmake.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, use_wait_cursor.cpp, and vertical_layout_panel.cpp.

◆ run() [2/3]

static void xtd::forms::application::run ( const form main_form)
static

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

Parameters
main_formA 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/forms/application>
#include <xtd/forms/form>
auto main() -> int {
}

◆ run() [3/3]

static void xtd::forms::application::run ( xtd::forms::application_context context)
static

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

Parameters
contextAn 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/forms/application>
#include <xtd/forms/application_context>
#include <xtd/forms/form>
using namespace xtd::forms;
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 += [&] {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 += [&] {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 += [&] {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);
}
Specifies the contextual information about an application thread.
Definition application_context.h:24

◆ startup_path()

static xtd::ustring xtd::forms::application::startup_path ( )
staticnoexcept

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]

static const xtd::forms::style_sheets::style_sheet & xtd::forms::application::style_sheet ( )
staticnoexcept

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]

static void xtd::forms::application::style_sheet ( const xtd::forms::style_sheets::style_sheet value)
static

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

Parameters
valueThe current xtd::forms::style_sheets::style_sheet style sheet.
Remarks
For more information, see Style sheets overview.

◆ style_sheet_names()

static const xtd::forms::style_sheets::style_sheet::style_sheet_names_t & xtd::forms::application::style_sheet_names ( )
staticnoexcept

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.

◆ style_sheets()

static const xtd::forms::style_sheets::style_sheet::style_sheets_t & xtd::forms::application::style_sheets ( )
staticnoexcept

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.

◆ system_controls() [1/2]

static bool xtd::forms::application::system_controls ( )
staticnoexcept

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]

static void xtd::forms::application::system_controls ( bool  value)
static

Sets a value indicating whether the system control is enabled.

Parameters
valuetrue if system control is enabled; otherwise false.
Exceptions
xtd::invalid_operation_exceptionIf 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]

static bool xtd::forms::application::system_font_size ( )
staticnoexcept

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

static void xtd::forms::application::system_font_size ( bool  value)
static

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

Parameters
valuetrue if the system font size is enabled; otherwise false.
Exceptions
xtd::invalid_operation_exceptionIf 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()

static const xtd::forms::style_sheets::style_sheet & xtd::forms::application::system_style_sheet ( )
staticnoexcept

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.

◆ use_visual_styles()

static bool xtd::forms::application::use_visual_styles ( )
staticnoexcept

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 0.4.0

◆ use_wait_cursor() [1/2]

static bool xtd::forms::application::use_wait_cursor ( )
staticnoexcept

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/forms/application>
#include <xtd/forms/button>
#include <xtd/forms/form>
#include <xtd/threading/thread>
using namespace xtd;
using namespace xtd::forms;
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 += [] {
application::use_wait_cursor(true);
for (auto count = 0; count < 500; ++count) {
application::do_events();
threading::thread::sleep(10_ms); // Simulate work...
}
application::use_wait_cursor(false);
};
}
private:
};
auto main() -> int {
}
@ button1
The first button on the message box is the default button.

◆ use_wait_cursor() [2/2]

static void xtd::forms::application::use_wait_cursor ( bool  use_wait_cursor)
static

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

Parameters
use_wait_cursortrue 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/forms/application>
#include <xtd/forms/button>
#include <xtd/forms/form>
#include <xtd/threading/thread>
using namespace xtd;
using namespace xtd::forms;
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 += [] {
application::use_wait_cursor(true);
for (auto count = 0; count < 500; ++count) {
application::do_events();
threading::thread::sleep(10_ms); // Simulate work...
}
application::use_wait_cursor(false);
};
}
private:
};
auto main() -> int {
}

◆ user_app_data_path()

static xtd::ustring xtd::forms::application::user_app_data_path ( )
staticnoexcept

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

◆ visual_styles() [1/2]

static bool xtd::forms::application::visual_styles ( )
staticnoexcept

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]

static void xtd::forms::application::visual_styles ( bool  value)
static

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

Parameters
valuetrue if visual styles are enabled; otherwise, false.
Exceptions
xtd::invalid_operation_exceptionIf 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.

Member Data Documentation

◆ application_exit

event<application, delegate<void(const event_args&)> > 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, delegate<void(const event_args&)> > 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, delegate<void(const event_args&)> > 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/forms/application>
#include <xtd/forms/form>
using namespace xtd;
using namespace xtd::forms;
namespace application_idle_example {
class form1 : public form {
public:
form1() {
application::idle += {*this, &form1::on_application_idle};
}
private:
void on_application_idle(const event_args& e) {
text(ustring::format("{}", ++counter));
}
int counter = 0;
};
}
auto main() -> int {
application::run(application_idle_example::form1 {});
}
Represents the base class for classes that contain event data, and provides a value to use for events...
Definition event_args.h:18

◆ leave_thread_modal

event<application, delegate<void(const event_args&)> > 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_exit

event<application, delegate<void(const event_args&)> > 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: