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

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

#include <application.hpp>

Static Public Member Functions

static void add_message_filter (const imessage_filter &value)
 Adds a message filter to monitor Windows messages as they are routed to their destinations. More...
 
static bool allow_quit ()
 Gets a value indicating whether the caller can quit this application. More...
 
static ustring common_app_data_path ()
 Gets the path for the application data that is shared among all users. More...
 
static ustring company_name ()
 Gets the company name associated with the application. More...
 
static void do_events ()
 Processes all Windows messages currently in the message queue. More...
 
static void enable_visual_styles ()
 Enables visual styles for the application. More...
 
static ustring executable_name ()
 Gets the executable name for the executable file that started the application, including the executable extension. More...
 
static ustring executable_path ()
 Gets the path for the executable file that started the application, including the executable name. More...
 
static void exit ()
 Informs all message pumps that they must terminate, and then closes all application windows after the messages have been processed. More...
 
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. More...
 
static void exit_thread ()
 Exits the message loop on the current thread and closes all windows on the thread. More...
 
static bool message_loop ()
 Gets a value indicating whether a message loop exists on this thread. More...
 
static const form_collection open_forms ()
 Gets a collection of open forms owned by the application. More...
 
static ustring product_name ()
 Gets the product name associated with this application. More...
 
static ustring product_version ()
 Gets the product version associated with this application. More...
 
static void raise_idle (const event_args &e)
 Raises the Idle event. More...
 
static ustring startup_path ()
 Gets the path for the executable file that started the application, not including the executable name. More...
 
static bool use_visual_styles ()
 Gets a value that indicates whether visual styles are enabled for the application. More...
 
static ustring user_app_data_path ()
 Gets the path for the application data of a user. More...
 

Static Public Attributes

static event< application, delegate< void(const event_args &)> > application_exit
 Occurs when the application is about to shut down. More...
 
static event< application, delegate< void(const event_args &)> > enter_thread_modal
 Occurs when the application is about to enter a modal state. More...
 
static event< application, delegate< void(const event_args &)> > idle
 Occurs when the application finishes processing and is about to enter the idle state. More...
 
static event< application, delegate< void(const event_args &)> > leave_thread_modal
 Occurs when the application is about to leave a modal state. More...
 
static event< application, delegate< void(const event_args &)> > thread_exit
 Occurs when a thread is about to shut down. More...
 

Detailed Description

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.

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.
Example
The following code example demonstrate the use of application class.
#include <xtd/xtd.forms>
int main() {
xtd::forms::application::run(xtd::forms::form());
}

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.

§ allow_quit()

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

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.

§ common_app_data_path()

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

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
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: and Settings directory. For more information, see Accessing Local and Remote Data in ClickOnce Applications.

§ company_name()

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

Gets the company name associated with the application.

Returns
The company name.
Remarks
company_name is taken from the application_informations containing the current application. You can set it by setting application_informations::company_name property. For more information, see application_informations.
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;;strings::format("The company name is: {0}", application::company_name);
}

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

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

Enables visual styles for the application.

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, nnable_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().

§ executable_name()

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

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 ustring xtd::forms::application::executable_path ( )
static

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.

§ message_loop()

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

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

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 ustring xtd::forms::application::product_name ( )
static

Gets the product name associated with this application.

Returns
The product name.
Remarks
product_name is taken from the application_informations containing the current application. You can set it by setting application_informations::product_name property. For more information, see application_informations.

§ product_version()

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

Gets the product version associated with this application.

Returns
The product version.
Remarks
product_version is taken from the application_informations containing the current application. You can set it by setting application_informations::product_version property. For more information, see application_informations.

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

§ startup_path()

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

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.

§ use_visual_styles()

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

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

§ user_app_data_path()

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

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

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.

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

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

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

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

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