Class GorgonApplication

An application class for windows Form applications.

Inheritance

object

GorgonApplication

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Namespace: Gorgon.UI

Assembly: Gorgon.Windows.dll

Syntax

public static class GorgonApplication

Remarks

This class is meant as a replacement for the standard windows forms Application class. It expands the functionality of the application class by exposing useful functionality for working with the main application Form.

One of the key components to this class is the introduction of a proper Idle loop. This allows an application to perform operations while the windows message pump is in an idle state. This is useful for things like games, or applications that require constant interaction with other systems. To set an idle loop you may pass a method to execute in one of the Run(Form, Func<bool>) method overloads. Or, if you choose, you may assign an idle method to execute at any point in the application life cycle by assigning a method to the IdleMethod.

Like the Application class, this class also provides the ability to pass a windows Form, or ApplicationContext to one of the Run(Form, Func<bool>) overloads.

tip

When passing a form to the Run(Form, Func<bool>) method, that form automatically becomes the main application window. The application will exit when this form is closed. The main form of an application may be retrieved from the MainForm property.

If this is not suitable, one of the other Run(Func<bool>) overloads will allow you to finely control the life cycle of your application.

Examples

An application that wishes to use this class instead of the Application class should follow this pattern:

// In program.cs:
[STAThread]
static void Main()
{
	try
	{
		Application.EnableVisualStyles();
		Application.SetCompatibleTextRenderingDefault(false);

		// Perhaps you could run initialization stuff here.			

		// This replaces:
		// Application.Run(new YourMainForm());

		// This will run with a form and an idle method named "Idle"
		GorgonApplication.Run(new YourMainForm(), Idle);
	}
	catch (Exception ex)
	{
		// You should always catch any unhandled exceptions and either log them, or display them, or something.
		// It can get real ugly for your users otherwise.
		ex.Catch(_ => GorgonDialogs.ErrorBox(null, _), GorgonApplication.Log);
	}
	finally
	{
		// Do your clean up here.
	}
}

Properties

AllowBackground

Property to set or return whether to allow the application message pump to continue running while the window is not focused or minimized.

Declaration

public static bool AllowBackground { get; set; }

Property Value

Type	Description
bool

Remarks

When set to true, this will allow an application to process messages and execute the IdleMethod while the application is unfocused or minimized. If it is set to false, the application will pause until it regains focus again.

It is recommended that this property be left at the default setting of false unless it's absolutely necessary to run the application in the background. On systems that use batteries, like laptops, setting this value to true could be detrimental to the battery life.

tip

If this property is set to true, there will be a delay corresponding to the value set on the UnfocusedSleepTime property. If that property is set to zero, then the application will process messages as though it were focused.

ApplicationContext

Property to set or return the current application context.

Declaration

public static ApplicationContext ApplicationContext { get; }

Property Value

Type	Description
ApplicationContext

Remarks

This value will return null if this application wasn't started with the Run(ApplicationContext, Func<bool>) method.

ComputerInfo

Property to return information about the computer.

Declaration

public static IGorgonComputerInfo ComputerInfo { get; }

Property Value

Type	Description
IGorgonComputerInfo

CurrentCulture

Property to set or return the current CultureInfo for the application.

Declaration

public static CultureInfo CurrentCulture { get; set; }

Property Value

Type	Description
CultureInfo

Remarks

This is a pass through for the CurrentCulture property.

See Also

CurrentCulture

CurrentInputLanguage

Property to return the current InputLanguage for the application.

Declaration

public static InputLanguage CurrentInputLanguage { get; }

Property Value

Type	Description
InputLanguage

Remarks

This is a pass through for the CurrentInputLanguage property.

See Also

CurrentInputLanguage

ExecutablePath

Property to return the path for the currently running application.

Declaration

public static string ExecutablePath { get; }

Property Value

Type	Description
string

Remarks

This includes the file name of the assembly that is executing as well as the directory that the application was executed from.

IdleMethod

Property to set or return the method to execute user code while the application is in an idle state.

Declaration

public static Func<bool> IdleMethod { get; set; }

Property Value

Type	Description
Func<bool>

Remarks

This property can be set at any time during the lifetime of the application. As soon as the application stops processing messages, it will execute the Func<TResult> assigned to it.

The property expects a function that returns a bool value. When this return value is true, then the application will continue processing messages. If it returns false, then the application will exit its message loop and shut down.

Setting this value to null when no MainForm or ApplicationContext is assigned will lead to an exception being thrown. This is because this method is the only thing the application has to do, and without it, there'd be no application processing.

warning

Do not set this to a non-null value when shutting down the application. Doing this will lead to undefined behaviour.

Exceptions

Type	Condition
InvalidOperationException	Thrown when an attempt to set this property to null is made and there is no MainForm or ApplicationContext attached to the application.

IsForeground

Property to return if the application is running in the foreground or background.

Declaration

public static bool IsForeground { get; }

Property Value

Type	Description
bool

Remarks

This determines whether the MainForm is focused (i.e. a top level, active window). It does this by ensuring the WindowState is not set to Minimized, and the window, or one of its child controls, currently has input focus.

This only applies to the MainForm. If Gorgon is required to keep processing unfettered, then set the AllowBackground property to true.

If AllowBackground is true, and the main form is not active, but another form belonging to the executing application is active, then processing will continue at full speed. But, if the entire application does not have focus, then Gorgon will limit the processing time to cycle every 16 milliseconds so as to not hog all the CPU.

If no MainForm is assigned, then this property will always return false.

IsRunning

Property to return if the GorgonApplication is in a running state or not.

Declaration

public static bool IsRunning { get; }

Property Value

Type	Description
bool

Remarks

When this value is true, the application message pump is running and processing messages.

Log

Property to set return the application log file interface.

Declaration

public static IGorgonLog Log { get; set; }

Property Value

Type	Description
IGorgonLog

Remarks

Setting this value to null will turn off logging for the application, but will not set the value to null. A dummy version of the log, that does no actual logging, will be used instead.

Ensure that the log being assigned to this property was created on the same thread as the application, otherwise an exception may be thrown.

MainForm

Property to return the main windows Form for the application.

Declaration

public static Form MainForm { get; }

Property Value

Type	Description
Form

Remarks

This property can be used to retrieve the Form that is the primary form for the application. When this form closes, the application will shut down.

This value is set when the Run(Form, Func<bool>) is used to run the application, or a form has been assigned to the MainForm property.

OpenForms

Property to return a read-only list of all the forms that are open in the application.

Declaration

public static FormCollection OpenForms { get; }

Property Value

Type	Description
FormCollection

Remarks

This is a pass through for the OpenForms property.

See Also

OpenForms

StartupPath

Property to return the directory for the currently running application.

Declaration

public static DirectoryInfo StartupPath { get; }

Property Value

Type	Description
DirectoryInfo

ThreadID

Property to return the ID of the application UI thread.

Declaration

public static int ThreadID { get; }

Property Value

Type	Description
int

UnfocusedSleepTime

Property to set or return the amount of time in milliseconds to sleep when the application window is not focused or minimized.

Declaration

public static int UnfocusedSleepTime { get; set; }

Property Value

Type	Description
int

Remarks

Settings this property to a value other than zero will tell the GorgonApplication to put the message pump to sleep for the requested number of milliseconds while the application is not focused. A value of zero, will tell the application to continuously process messages regardless of focus state.

This has value for systems that run on batteries, like a laptop, where unnecessary processing can be detrimental to battery life.

tip

This value has no effect if the AllowBackground property is set to false.

warning

Do not set this value to a large number, doing so will stall the message pump and cause issues for the application. A value of 10 milliseconds (the default) is small enough to keep the application responsive.

Methods

AddMessageFilter(IMessageFilter)

Function to add a message filter to intercept application messages.

Declaration

public static void AddMessageFilter(IMessageFilter filter)

Parameters

Type	Name	Description
IMessageFilter	filter	A IMessageFilter used to intercept an application message.

Remarks

This is a pass through for the AddMessageFilter(IMessageFilter) method.

See Also

AddMessageFilter(IMessageFilter)

Quit()

Function that will signal the application to begin shutdown.

Declaration

public static void Quit()

Remarks

This will signal the application to tell it that it is time to shut down. This shut down will not happen immediately as the application needs to finish up whatever processing it is doing before exiting.

RemoveMessageFilter(IMessageFilter)

Function to remove a message filter added with the AddMessageFilter(IMessageFilter) method.

Declaration

public static void RemoveMessageFilter(IMessageFilter filter)

Parameters

Type	Name	Description
IMessageFilter	filter	A IMessageFilter used to intercept an application message.

Remarks

This is a pass through for the RemoveMessageFilter(IMessageFilter) method.

See Also

RemoveMessageFilter(IMessageFilter)

Run(Func<bool>)

Function to begin execution of a GorgonApplication.

Declaration

public static void Run(Func<bool> idleMethod)

Parameters

Type	Name	Description
Func<bool>	idleMethod	A method to execute while the application is idle.

Remarks

This method begins execution of the application by starting its messaging pump and processing application messages.

This overload only uses the IdleMethod for its execution. This is called when the application has no messages to process in its message pump. Because of this, there is no indication of whether the application is in the foreground or background as it is really always running in the background. When this method is chosen, the IsForeground property will always return false. Applications that use this should take care to balance the CPU usage of the idleMethod.

The idleMethod takes a Func<TResult> that returns a bool value. When this value is true, the application will continue processing as normal, but when it returns false, the application will exit.

important

Only one thread may call this method at any given time. If this method is executed by a thread, and another attempts to execute it, an exception will be thrown.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the idleMethod parameter is null.
InvalidOperationException	Thrown when the application is already executing. Check the IsRunning property before calling this method.

See Also

IsForeground

ApplicationContext

IsRunning

IdleMethod

Run(ApplicationContext, Func<bool>)

Function to begin execution of a GorgonApplication.

Declaration

public static void Run(ApplicationContext context, Func<bool> idleMethod = null)

Parameters

Type	Name	Description
ApplicationContext	context	The ApplicationContext to use for this application.
Func<bool>	idleMethod	[Optional] A method to execute while the application is idle.

Remarks

This method begins execution of the application by starting its messaging pump and processing application messages.

This particular overload takes a ApplicationContext which allows for more fine grained control over the lifetime of the application.

The idleMethod is called while the application is idle (i.e. not processing messages). User code may execute within this method to allow for processing while the application is not doing anything.

tip

The idleMethod takes a Func<TResult> that returns a bool value. When this value is true, the application will continue processing as normal, but when it returns false, the application will exit.

important

Only one thread may call this method at any given time. If this method is executed by a thread, and another attempts to execute it, an exception will be thrown.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the context parameter is null.
InvalidOperationException	Thrown when the application is already executing. Check the IsRunning property before calling this method.

See Also

ApplicationContext

IsRunning

IdleMethod

Run(Form, Func<bool>)

Function to begin execution of a GorgonApplication.

Declaration

public static void Run(Form mainForm, Func<bool> idleMethod = null)

Parameters

Type	Name	Description
Form	mainForm	The main application Form to use for this application.
Func<bool>	idleMethod	[Optional] A method to execute while the application is idle.

Remarks

This method begins execution of the application by starting its messaging pump and processing application messages.

This overload uses the mainForm passed to it as the main application form. When this window closes, the application will shut down.

The idleMethod is called while the application is idle (i.e. not processing messages). User code may execute within this method to allow for processing while the application is not doing anything.

tip

The idleMethod takes a Func<TResult> that returns a bool value. When this value is true, the application will continue processing as normal, but when it returns false, the application will exit.

important

Only one thread may call this method at any given time. If this method is executed by a thread, and another attempts to execute it, an exception will be thrown.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the mainForm parameter is null.
InvalidOperationException	Thrown when the application is already executing. Check the IsRunning property before calling this method.

See Also

ApplicationContext

IsRunning

IdleMethod

MainForm

Events

Exit

Event fired when the application is about to exit.

Declaration

public static event EventHandler Exit

Event Type

Type	Description
EventHandler

ThreadExit

Event fired when a message pump thread is about to exit.

Declaration

public static event EventHandler ThreadExit

Event Type

Type	Description
EventHandler