[Overview][Constants][Types][Classes][Procedures and functions][Variables][Index] | Reference for unit 'Forms' (#lcl)

# TApplication

[Properties (by Name)] [Methods (by Name)] [Events (by Name)]

Application management and configuration for a GUI application.

## Declaration

Source position: forms.pp line 1458

`type TApplication = class(TCustomApplication)`
`protected`
`function GetConsoleApplication; override;` |  | Always returns False for a GUI application.
`procedure NotifyIdleHandler();` |  | Signals all idle handlers for the application.
`procedure NotifyIdleEndHandler;` |  | Notifies all Idle End handlers when a new message has arrived.
`procedure NotifyActivateHandler;` |  | Notifies all Activate handlers for the application.
`procedure NotifyDeactivateHandler;` |  | Notifies all Deactivate handlers for the application.
`procedure NotifyCustomForms();` |  | Performs the specified message for all custom forms in the application.
`function IsHintMsg();` |  | Exists for Delphi compatibility only.
`function DoOnHelp(); virtual;` |  | Signals an OnHelp event handler.
`procedure DoOnMouseMove; virtual;` |  | OnMouseMove message handler, updates the Hint.
`procedure ShowHintWindow();` |  | Shows or hides the hint window for a control in the application.
`procedure OnHintTimer();` |  | Implements an event handler signalled when the timer for a hint display has elapsed.
`procedure SetTitle(); override;` |  | Sets the value for the Title property.
`procedure StartHintTimer();` |  | Starts the timer for display of a hint message.
`procedure UpdateVisible;` |  | Asks the widgetset to update its task bar entries.
`procedure DoIdleActions;` |  | Updates all Actions and hides splash screens.
`procedure MenuPopupHandler();` |  | Implements the OnMenuPopupHandler for the application.
`procedure ProcessAsyncCallQueue;` |  | Calls all methods queued in QueueAsyncCall.
`procedure DoDecLCLRefcountToZero();` |  | Performs actions needed when the reference count for a TLCLComponent instance reaches 0 in the application.
`procedure FreeComponent();` |  | Destroys all components marked for release.
`procedure ReleaseComponents;` |  | Destroys all components marked for release.
`procedure DoBeforeFinalization;` |  | Destroys all components.
`function GetParams(); override;` |  | Returns the command line argument at the specified ordinal position.
`public`
`constructor Create(); override;` |  | Constructor for the class instance.
`destructor Destroy; override;` |  | Destructor for the class instance.
`procedure ActivateHint();` |  | Configures a hint window for the specified mouse position.
`function GetControlAtMouse;` |  | Gets the control under the mouse pointer.
`function GetControlAtPos();` |  | Gets the control which contains the specified position, and optionally updates the internal tracking members for mouse capture when needed.
`procedure ControlDestroyed();` |  | Clears all references to the destroyed control.
`function BigIconHandle;` |  | Returns the Handle for the large application Icon.
`function SmallIconHandle;` |  | Returns the Handle for the small application Icon.
`procedure BringToFront;` |  | Asks the widgetset to bring the last form for the application in front of all other programs.
`procedure CreateForm();` |  | Creates a Form or component owned by the Application instance.
`procedure UpdateMainForm();` |  | Makes the specified form the MainForm in the Application.
`procedure QueueAsyncCall();` |  | Inserts an asynchronous call into the queue.
`procedure RemoveAsyncCalls();` |  | Removes all calls added via QueueAsyncCall.
`procedure ReleaseComponent();` |  | Safely destroys a component used in the application.
`function ExecuteAction(); override;` |  | Signals an OnActionExecute handler (when assigned).
`function UpdateAction(); override;` |  | Signals an OnActionUpdate handler (when assigned).
`procedure HandleException(); override;` |  | HandleException method for handling an exception; attempts to maintain program execution if possible, otherwise exits gracefully.
`procedure HandleMessage;` |  | Handles pending messages, and enters the Idle state.
`function HelpCommand();` |  | Show help.
`function HelpContext();` |  | Shows context-sensitive help for the application.
`function HelpKeyword();` |  | Shows help for the specified keyword.
`function HelpShowTableOfContents;` |  | Displays the Help Table of Contents using the Help Manager for the application.
`procedure ShowHelpForObject();` |  | When Sender is a TControl, invoke its ShowHelp method.
`procedure RemoveStayOnTop();` |  | Removes the StayOnTop attribute from all visible forms in the application.
`procedure RestoreStayOnTop();` |  | Restores StayOnTop for all forms changed by RemoveStayOnTop.
`function IsWaiting;` |  | True if the application is waiting for a message event.
`procedure CancelHint;` |  | Called when the Hint timer has expired to stop showing the Hint.
`procedure HideHint;` |  | Hides the Hint window.
`procedure HintMouseMessage();` |  | Called when the mouse is over a control with a Hint.
`procedure Initialize; override;` |  | Initializes the widgetset (and more).
`function MessageBox();` |  | Display an message dialog with response buttons.
`procedure Minimize;` |  | Asks the widgetset to minimize the application.
`procedure ModalStarted;` |  | Called when a modal form display is started.
`procedure ModalFinished;` |  | Called when a modal form is closed.
`procedure Restore;` |  | Restores a previously minimized application.
`procedure Notification(); override;` |  | Performs actions when a component is added to or removed from the application.
`procedure ProcessMessages;` |  | Call this method during lengthy operations to ensure the GUI remains responsive.
`procedure Idle();` |  | Called when the application enters the idle state.
`procedure Run;` |  | Loads the form and passes control to the event loop for the application.
`procedure ShowException(); override;` |  | Shows the message for the specified exception and asks the user to abort or continue.
`procedure Terminate; override;` |  | The application is terminated and the component engine is shutdown.
`procedure DisableIdleHandler;` |  | Disables Idle handling.
`procedure EnableIdleHandler;` |  | Resumes Idle handling.
`procedure NotifyUserInputHandler();` |  | Notifies all user input handlers of the specified message.
`procedure NotifyKeyDownBeforeHandler();` |  | Notifies all ahtKeyDownBefore handlers.
`procedure NotifyKeyDownHandler();` |  | Notifies all ahtKeyDownAfter handlers, and eventually reacts to F1 (Help).
`procedure ControlKeyDown();` |  | Handles KeyDown events in a Control, e.g. handles navigation keys.
`procedure ControlKeyUp();` |  | Handles KeyUp events in a Control, e.g. handles Enter and Esc keys.
`procedure AddOnIdleHandler();` |  | Adds an application Idle handler to the list of handlers for the type.
`procedure RemoveOnIdleHandler();` |  | Removes an application Idle handler for the list of handlers for the type.
`procedure AddOnIdleEndHandler();` |  | Adds an application IdleEnd handler to the list of handlers for the type.
`procedure RemoveOnIdleEndHandler();` |  | Removes an application IdleEnd handler.
`procedure AddOnUserInputHandler();` |  | Adds an application user input handler to the list of handlers for the type.
`procedure RemoveOnUserInputHandler();` |  | Removes an application user input handler from the list of handlers for the type.
`procedure AddOnKeyDownBeforeHandler();` |  | Adds an application key down before interface handler.
`procedure RemoveOnKeyDownBeforeHandler();` |  | Removes an application key down before interface handler.
`procedure AddOnKeyDownHandler();` |  | Adds an application key down handler to the list for the type.
`procedure RemoveOnKeyDownHandler();` |  | Removes an application key down after interface handler.
`procedure AddOnActivateHandler();` |  | Adds an application activation handler.
`procedure RemoveOnActivateHandler();` |  | Removes an application activation handler.
`procedure AddOnDeactivateHandler();` |  | Adds an application deactivation handler.
`procedure RemoveOnDeactivateHandler();` |  | Removes an application deactivation handler.
`procedure AddOnExceptionHandler();` |  | Adds an application exception handler.
`procedure RemoveOnExceptionHandler();` |  | Removes an application exception handler.
`procedure AddOnEndSessionHandler();` |  | Adds an application logoff handler.
`procedure RemoveOnEndSessionHandler();` |  | Removes an application logoff handler.
`procedure AddOnQueryEndSessionHandler();` |  | Adds an application logoff query handler.
`procedure RemoveOnQueryEndSessionHandler();` |  | Removes an application logoff query handler.
`procedure AddOnMinimizeHandler();` |  | Adds an application minimizing handler.
`procedure RemoveOnMinimizeHandler();` |  | Removes an application minimizing handler.
`procedure AddOnModalBeginHandler();` |  | Adds an application becoming modal handler.
`procedure RemoveOnModalBeginHandler();` |  | Removes an application becoming modal handler.
`procedure AddOnModalEndHandler();` |  | Adds an application exiting modal state handler.
`procedure RemoveOnModalEndHandler();` |  | Removes an application exiting modal state handler.
`procedure AddOnRestoreHandler();` |  | Adds an application exiting minimized state handler.
`procedure RemoveOnRestoreHandler();` |  | Removes an application exiting minimized state handler.
`procedure AddOnDropFilesHandler();` |  | Adds an application dropped files handler.
`procedure RemoveOnDropFilesHandler();` |  | Removes an application dropped files handler.
`procedure AddOnHelpHandler();` |  | Adds an application Help handler.
`procedure RemoveOnHelpHandler();` |  | Removes an application Help handler.
`procedure AddOnHintHandler();` |  | Adds an application Hint handler.
`procedure RemoveOnHintHandler();` |  | Removes an application Hint handler.
`procedure AddOnShowHintHandler();` |  | Adds an application Hint show handler to the list for the handler type.
`procedure RemoveOnShowHintHandler();` |  | Removes an application Hint show handler from the list for the handler type.
`procedure AddOnGetMainFormHandleHandler();` |  | Adds a handler signalled when the application MainForm handle is retrieved.
`procedure RemoveOnGetMainFormHandleHandler();` |  | Removes a handler used to get the handle for the main form in the application.
`procedure AddOnActionExecuteHandler();` |  | Adds the specified routine to the list of ahtActionExecute handlers for the application.
`procedure RemoveOnActionExecuteHandler();` |  | Removes the specified routine from the list of ahtActionExecute handlers for the application.
`procedure AddOnActionUpdateHandler();` |  | Adds the specified routine to the list of ahtActionUpdate handlers for the application.
`procedure RemoveOnActionUpdateHandler();` |  | Removes the specified routine from the list of ahtActionUpdate handlers for the application.
`procedure RemoveAllHandlersOfObject(); virtual;` |  | Removes all handlers implemented for the specified object.
`procedure DoBeforeMouseMessage();` |  | Performs actions needed before a mouse message is processed in the application.
`function IsShortcut();` |  | Checks whether a handler is available for the shortcut key in the message.
`procedure IntfQueryEndSession();` |  | Called by the interface to confirm the end of a session.
`procedure IntfEndSession;` |  | Called by the interface when the session ends.
`procedure IntfAppActivate();` |  | Called by the interface on application activation.
`procedure IntfAppDeactivate();` |  | Called by the interface on application deactivation.
`procedure IntfAppMinimize;` |  | Called by the interface when the application is minimized.
`procedure IntfAppRestore;` |  | Called by the interface when the application is restored.
`procedure IntfDropFiles();` |  | Called by the interface when files have been dropped.
`procedure IntfSettingsChange;` |  | Called when the WM_SETTINGCHANGE message is handled for the application.
`procedure IntfThemeOptionChange();` |  | Called by the interface when a theme option has changed.
`function IsRightToLeft;` |  | Indicates if BiDiMode contains a value other than bdLeftToRight.
`function IsRTLLang();` |  | Checks the given language name for use of right-to-left reading.
`function Direction();` |  | Gets the TBidiMode value with the direction for the specified language name.
`procedure DoArrowKey();` |  | Uses arrow keys for navigation, if enabled.
`procedure DoTabKey();` |  | Uses the Tab key for navigation, if enabled.
`procedure DoEscapeKey();` |  | Interprets Esc as Cancel action, if applicable.
`procedure DoReturnKey();` |  | Interprets Enter as the default action, if applicable.
`property Active: Boolean; [r]` |  | True if the application is focused.
`property ActiveFormHandle: HWND; [r]`
`property ApplicationType: TApplicationType; [rw]` |  | The type of the application (i.e. the sort of device for which it is intended).
`property BidiMode: TBiDiMode; [rw]` |  | The bidirectional mode to use.
`property CaptureExceptions: Boolean; [rw]` |  | Enables exception handling in the Application.
`property DoubleBuffered: TApplicationDoubleBuffered; [rw] platform ;` |  | Indicates if the application uses double buffering.
`property ExtendedKeysSupport: Boolean; [rw]` |  | Controls whether extended key codes are available in key down and key up messages.
`property ExceptionDialog: TApplicationExceptionDlg; [rw]` |  | Indicates the dialog type used for an exception in the application.
`property FindGlobalComponentEnabled: Boolean; [rw]` |  | Enables searching for global components by name.
`property Flags: TApplicationFlags; [rw]` |  | Contains state flags for the application.
`property Handle: TLCLHandle; [rw] platform ;` |  | Provides access to the handle for the application instance.
`property Hint: string; [rw]` |  | The current Hint text active for the application.
`property HintColor: TColor; [rw]` |  | The background color for a Hint window.
`property HintHidePause: Integer; [rw]` |  | Indicates how long a Hint remains visible after the mouse pointer is moved.
`property HintHidePausePerChar: Integer; [rw]` |  | Indicates how long a keystroke extends the time a Hint remains visible (added to HintHidePause).
`property HintPause: Integer; [rw]` |  | The delay before a Hint is shown for a form or control.
`property HintShortCuts: Boolean; [rw]` |  | Enables or disables display of keyboard shortcuts (e. g. on menu items).
`property HintShortPause: Integer; [rw]` |  | The pause before a different Hint is displayed.
`property Icon: TIcon; [rw]` |  | The icon associated with this application.
`property LayoutAdjustmentPolicy: TLayoutAdjustmentPolicy; [rw]` |  | Indicates the layout and sizing policy used for forms and controls in the application.
`property Navigation: TApplicationNavigationOptions; [rw]` |  | Allows switching between controls using keyboard navigation.
`property MainForm: TForm; [r]` |  | Contains the main form for the application.
`property MainFormHandle: HWND; [r]` |  | Window handle for the MainForm in the application.
`property MainFormOnTaskBar: Boolean; [rw] platform ;` |  | Controls whether a button is displayed on the task bar for the main form in the application.
`property ModalLevel: Integer; [r]` |  | The number of modal forms shown.
`property MoveFormFocusToChildren: Boolean; [rw]` |  | Indicates if an active control is focused when a form receives focus.
`property MouseControl: TControl; [r]` |  | Contains the control currently under the mouse pointer.
`property TaskBarBehavior: TTaskBarBehavior; [rw]` |  | Indicates how forms are represented in the task bar.
`property UpdateFormatSettings: Boolean; [rw] platform ;` |  | Indicates if application format settings are updated when changed in a widgetset class.
`property OnActionExecute: TActionEvent; [rw]` |  | Default handler for unhandled Actions.
`property OnActionUpdate: TActionEvent; [rw]` |  | Event handler signalled to update actions used in the application.
`property OnActivate: TNotifyEvent; [rw]` |  | Event handler signalled when an Activate message is handled in the application.
`property OnDeactivate: TNotifyEvent; [rw]` |  | Event handler signalled when a Deactivate message is handled in the application.
`property OnGetMainFormHandle: TGetHandleEvent; [rw]` |  | Event handler used to provide a value for the MainFormHandle property.
`property OnIdle: TIdleEvent; [rw]` |  | Event handler signalled when the application enters the idle state.
`property OnIdleEnd: TNotifyEvent; [rw]` |  | Event handler signalled when the application leaves the Idle state.
`property OnEndSession: TNotifyEvent; [rw]` |  | Event handler signalled when a session is ended in the application.
`property OnQueryEndSession: TQueryEndSessionEvent; [rw]` |  | Event handler signalled to determine if the current session be be ended, and the application can be closed.
`property OnMinimize: TNotifyEvent; [rw]` |  | Event handler signalled when the application is minimized.
`property OnMessageDialogFinished: TModalDialogFinished; [rw]` |  | Event handler signalled when a message dialog in the application has been completed.
`property OnModalBegin: TNotifyEvent; [rw]` |  | Event handler signalled when a form in the application is displayed as a modal form.
`property OnModalEnd: TNotifyEvent; [rw]` |  | Event handler signalled when the last modal form for the application has been exited.
`property OnRestore: TNotifyEvent; [rw]` |  | Event handler signalled when the application is restored from a minimized / maximized state.
`property OnDropFiles: TDropFilesEvent; [rw]` |  | Event handler signalled when file(s) are dropped into the application.
`property OnHelp: THelpEvent; [rw]` |  | Event handler signalled when help is requested in the application.
`property OnHint: TNotifyEvent; [rw]` |  | Event handler signalled when a hint is requested in the application.
`property OnShortcut: TShortCutEvent; [rw]` |  | Event handler signalled to determine if a keystroke message is a shortcut key in the application.
`property OnShowHint: TShowHintEvent; [rw]` |  | Event handler signalled prior to displaying a hint window.
`property OnUserInput: TOnUserInputEvent; [rw]` |  | Event handler signalled to handle user input messages.
`property OnDestroy: TNotifyEvent; [rw]` |  | Event handler signalled when the application is freed.
`property OnCircularException: TExceptionEvent; [rw]` |  | Event handler signalled when a circular exception occurs before the application is halted.
`property ShowButtonGlyphs: TApplicationShowGlyphs; [rw]` |  | Allows the platform defaults for glyphs on buttons to be overridden.
`property ShowMenuGlyphs: TApplicationShowGlyphs; [rw]` |  | Sets the default policy for showing or hiding glyph images in menus.
`property ShowHint: Boolean; [rw]` |  | Indicates if Hints are displayed for the application.
`property ShowMainForm: Boolean; [rw]` |  | Allows the main form to be shown or hidden when an application is started.
`property Title: string; [rw]` |  | Contains the title for the application.
`property Scaled: Boolean; [rw]` |  | Indicates if forms and controls in the application can be scaled to different display densities (Pixels per Inch).
`end;`

## Inheritance

`TApplication` |  | Application management and configuration for a GUI application.
`TCustomApplication`
?
`TObject`

## Description

TApplication is a TCustomApplication descendant which provides facilities used to manage and configure a GUI application. Properties, methods, and event handlers are provided which allow a program to create, execute, monitor, maintain and destroy an application and its forms. Every GUI application contains an Application variable that represents the TApplication or descendent class instance.

TApplication provides a message processing loop that includes hooks for event handlers and exception handling, and supports dispatching messages for TCustomAction instances used in application forms. TApplication provides support for hints and content-sensitive help for forms and controls used in the application. Convenience methods, like MessageBox, are provided to simplify access to dialogs and error messages in the application.

Remark: | For the macOS Carbon widgetset, an application is executed via the Application Bundle. As a result, command line parameters are not available to the application instance. The OnDropFiles event handler must be used to detected when associated files need to be opened.

## See also

TApplication.GetParams |  | Returns the command line argument at the specified ordinal position.
TApplication.OnDropFiles |  | Event handler signalled when file(s) are dropped into the application.
ParamStrUTF8
TCustomApplication.ExeName
TCustomApplication.Params
TCustomApplication.ParamCount