Class

Application


Warning

This item was deprecated in version 2021r3. Please use DesktopApplication as a replacement.

Description

Contains properties, methods, and events for managing desktop applications.

Methods

Name

Parameters

Returns

Shared

AddTrayItem

Item As TrayItem

Boolean

DoEvents

[milliseconds As Integer]

HideTooltip

NewDocument

OpenDocument

File As FolderItem

RefreshMenuBar

RemoveTrayItem

Item As TrayItem

ShowTooltip

tip As String, x As Integer, y As Integer, autoHide As Boolean

Window

index As Integer

Window

Constants

The following class constants can be used to specify the value of the StageCode property.

Constant

Value

Development

0

Alpha

1

Beta

2

Final

3

Property descriptions


Application.AllowAutoQuit

AllowAutoQuit As Boolean

When True, the Application quits when the last window is closed, whether by calling the Close method of the Window class or by the user closing the last window manually.

AllowAutoQuit defaults to True on non-MDI Windows applications and True on Linux. It defaults to False on MDI Windows and macOS applications.

This code is in the Open event of the App class.

App.AllowAutoQuit = True

Application.AllowDarkMode

AllowDarkMode As Boolean

You can only set this property in the Inspector for the App object. Set to ON to make the app run in dark mode when dark mode is set in the OS settings. This is set to False by default.

This property is read-only.

For macOS, Dark mode is only relevant on macOS Mojave (10.14) or later.


Application.AllowHiDPI

AllowHiDPI As Boolean

You can only set this property in the Inspector for the App object. Set to ON to make the app HiDPI-aware. This is set to True by default.

This property is read-only.

You can read this property at runtime:

If App.AllowHiDPI Then
  ' HiDPI is enabled
Else
  ' HiDPI is not enabled
End If

When AllowHiDPI is turned OFF, the framework will continue to work the way it did before. Images that use @2x or @3x in the name will have their PPI (points per inch) adjusted accordingly (144ppi, 216ppi).

You can turn the AllowHiDPI property on or off dynamically by using an IDE Script. This turns it on:

PropertyValue("App.AllowHiDPI") = "True"

Use the text "False" to turn it off.

When AllowHiDPI is turned ON, the framework will NOT change the ppi when an image with @2x or @3x in its name is loaded. It is up to you to set the PPI (which is most easily handled using an Image Set). The reason for this is so that if you need access to the image's original PPI, you'll be able to get it by manually loading the image and setting is PPI.

If you want to set the PPI automatically based on its name, you can use this method:

Sub SetImageResolutionFromName(p As Picture, filename As String)
  Var r As New RegEx
  r.SearchPattern = "@([0-9.]+)x\."

  Var rm As RegExMatch = r.Search(filename)
  If rm <> Nil And rm.SubExpressionCount > 0 Then
    Var n As Double = CDbl(rm.SubExpressionString(1))
    p.HorizontalResolution = 72 * n
    p.VerticalResolution = 72 * n
  End If
End Sub

Application.BugVersion

BugVersion As Integer

The version you increment when the release of your Application is only to fix critical and unexpected bugs in the previous release.

This property is read-only.

This can only be set in the IDE, but you can read the value in your code.

Typically version numbers are written as 1.2.3.4 (MajorVersion.MinorVersion.BugVersion.NonReleaseVersion).

Note

On Windows valid values are between 0 to 255.

Puts all the individual versions together to create the full version:

Var fullVersion As String
fullVersion = app.MajorVersion.ToString + "." + app.MinorVersion.ToString + "." _
  + app.BugVersion.ToString + "." + app.NonReleaseVersion.ToString.

Application.BuildDateTime

BuildDateTime As DateTime

Contains the date and time when the Application was built.

This property is read-only.

You can also access the CreationDateTime property of the Application's FolderItem by calling App.ExecutableFile.CreationDate.

The following code gets the build date/time and displays it in a Label.

Var d As DateTime
d = App.BuildDateTime

Label1.Text = d.ToString

Application.Copyright

Copyright As String

A longer text description for the app. Usually this contains the app name, copyright, version and other information. This is displayed by some operating systems in Get Info or Property windows for the app. This property can be set only in the IDE.

This property is read-only.

Display the copyright info:

MessageBox(App.Copyright)

Application.Description

Description As String

A text description for the app that may be displayed by some operating systems in Get Info or Property windows for the app. This property can be set only in the IDE. This value is not displayed for macOS.

This property is read-only.


Application.DockItem

DockItem As DockItem

Enables you to manipulate the dock item associated with the Application (macOS only).

The DockItem property enables you to access the properties and methods of the DockItem class. This class has two methods, UpdateNow and ResetIcon, and one property, Graphics. Use the methods of the Graphics class to modify the appearance of the icon. Since a macOS icon is intended to be scaled automatically, you should design it as a 512x512 pixel icon.

  • ResetIcon resets the icon to its original state (default appearance).

  • Call the UpdateNow method to redraw the icon.

You can also use the ClearRect property of the Graphics class to start over from a blank icon. Anything you can do with a Graphics object you are able to do with the Dock's Graphics object (like drawing in a picture or using a Group2D). The DockItem property of the Window class enables you to control the dock item for individual windows.


Application.ExecutableFile

ExecutableFile As FolderItem

Returns a FolderItem for the actual executable Application even if it is in a bundle.

This property is read-only.

Application.ExecutableFile returns Nil if the app has been deleted or an error occurs finding it.

Use the properties and methods of the FolderItem class to get/set attributes of the executable file and/or perform operations. For example:

Var appPath As String
appPath = App.ExecutableFile.NativePath

gets the full path to the executable.

Var cd As DateTime
cd = App.ExecutableFile.CreationDateTime

gets the date/time the executable was created.

You can get the location of the folder in which the app is running, by getting the Parent of the executable file:

Var f As FolderItem
f = App.ExecutableFile.Parent

Application.LastWindowIndex

LastWindowIndex As Integer

Returns the index of the last window the app opened.

This property is read-only.


Application.MajorVersion

MajorVersion As Integer

The version to be incremented when the release includes many large new features.

This property is read-only.

This can only be set in the IDE, but you can read the value in your code.

Typically version numbers are written as 1.2.3.4 (MajorVersion.MinorVersion.BugVersion.NonReleaseVersion).

Note

On Windows valid values are between 0 to 255.

Puts all the individual versions together to create the full version:

Var fullVersion As String
fullVersion = app.MajorVersion.ToString + "." + app.MinorVersion.ToString + "." _
  + app.BugVersion.ToString + "." + app.NonReleaseVersion.ToString.

Application.MDIWindow

MDIWindow As MDIWindow

Provides access to the properties and methods of the MDIWindow class.

Valid only for Windows apps that are built using the Multiple Document Interface option.

This code sets the Title property of the app's MDI window.

App.MDIWindow.Title = "The MDI Window Title"

Application.MenuBar

MenuBar As MenuBar

Represents the Application's global menubar. Its children are the menus.

The Application MenuBar is used by macOS when a Window does not have a specified MenuBar. It is also used by MDI applications on Windows to display the MDI window MenuBar.

The Application MenuBar property is not used by non-MDI Windows applications or Linux applications.

However, if the Application MenuBar property is specified, it will be automatically filled in as the MenuBar on any new Windows you create.

This line of code in the Open event of the App class sets the menubar to a user-created menubar. This can also be done in the Properties pane in the IDE.

App.MenuBar = MenuBar2

Application.MinorVersion

MinorVersion As Integer

The version you increment when the release is does not add any major features.

This property is read-only.

This can only be set in the IDE, but you can read the value in your code.

Typically version numbers are written as 1.2.3.4 (MajorVersion.MinorVersion.BugVersion.NonReleaseVersion).

Note

On Windows valid values are between 0 to 255.

Puts all the individual versions together to create the full version:

Var fullVersion As String
fullVersion = app.MajorVersion.ToString + "." + app.MinorVersion.ToString + "." _
  + app.BugVersion.ToString + "." + app.NonReleaseVersion.ToString.

Application.MouseCursor

MouseCursor As MouseCursor

The cursor that is displayed while the Application is running and the pointer is within one of the Application's windows.

On Mac, it is also the cursor that is displayed when the app is frontmost and the pointer moves outside of any of the app's windows. On Windows and Linux, the pointer changes back to the default pointer when it exits an Application window. If the Application class MouseCursor is not Nil, the non-Nil MouseCursor properties belonging to any Window or Control are ignored.

You can use the cursors in the Cursors module to set the mouse cursor.

This line in the Open event of the App class sets the default cursor to the finger pointer.

App.MouseCursor = System.Cursors.FingerPointer

Application.NonReleaseVersion

NonReleaseVersion As Integer

The version you increment each time you build your project.

This property is read-only.

This can only be set in the IDE, but you can read the value in your code.

Some platforms also refer to this as the build or revision number.

Typically version numbers are written as 1.2.3.4 (MajorVersion.MinorVersion.BugVersion.NonReleaseVersion).

If AutoIncrementVersionInformation is checked, the IDE increases NonReleaseVersion by one each time you build your project, but not when you run it.

Note

On Windows valid values are between 0 to 255.

If your app is rejected by an App Store for something minor, you can resolve it then increment this number to (in most cases) sufficiently distinguish it from the version you previously submitted.

Puts all the individual versions together to create the full version:

Var fullVersion As String
fullVersion = app.MajorVersion.ToString + "." + app.MinorVersion.ToString + "." _
  + app.BugVersion.ToString + "." + app.NonReleaseVersion.ToString.

Application.RegionCode

RegionCode As Integer

The Region Code of the Application, corresponding to the version information. Not supported on Windows. This property can be set only in the IDE.

This property is read-only.


Application.StageCode

StageCode As Integer

Stage Code of the Application, corresponding to the version information.

This property is read-only.

Use the four Application class constants to set/get the Stage. Stage can be set only in the IDE.

Value

Description

0

Development

1

Alpha

2

Beta

3

Final


Application.Version

Version As String

A short text description for the app. Usually this contains just the version number (such as 1.2.3.4) and is displayed by some operating systems in Get Info or Property windows for the app. This property can be set only in the IDE.

This property is read-only.

Typically version numbers are written as 1.2.3.4.

Version is displayed by the file information windows on macOS (Finder, Get Info) and Windows (Windows Explorer, Properties).

Display the short version:

MessageBox(App.Version)

Application.WindowCount

WindowCount As Integer

Returns the number of open windows.

This property is read-only.

The WindowCount property includes any windows that are invisible. If called during a window's Open event, it includes that window. If called during a window's Close event, it does not include that window.

Method descriptions


Application.AddTrayItem

AddTrayItem(Item As TrayItem) As Boolean

Adds the passed item to the System Tray via the TrayItem class.

AddTrayItem returns a Boolean that indicates success or failure. If it returns True, the TrayItem was added successfully. The System Tray is supported on Windows and Linux only. See the TrayItem class.


Application.DoEvents

DoEvents([milliseconds As Integer])

Yields time back to your app when in loops. Intended for console applications in which there is no main event loop.


Application.HideTooltip

HideTooltip

Hides the tooltip. Call this if the AutoHide parameter of the ShowTooltip method was False.

Call this if you had passed False to the corresponding call to ShowTooltip or you are not programming for macOS and need to hide the tooltip manually.

App.HideTooltip

Application.NewDocument

NewDocument

Calls the NewDocument event handler.


Application.OpenDocument

OpenDocument(File As FolderItem)

Calls the OpenDocument event handler.


Application.RefreshMenuBar

RefreshMenuBar

Forces an update of the menu bar and calls EnableMenu and EnableMenuItem event handlers.

In most cases, the standard menu bar updating will be sufficient. There are cases, however, when it's not. For example, if the SelChange event handler of a TextField control causes all of the menu items in a particular menu to be disabled, the menu itself should be disabled. Unfortunately, it won't be because the user has not yet clicked in the menu bar. Under circumstances like this, you can call the RefreshMenuBar method to force your app to only update the menus based on your own conditions.

Calling this calls EnableMenu or EnableMenuItem event handlers on Application, Window, ContainerControl and MenuItem.

App.RefreshMenuBar

Application.RemoveTrayItem

RemoveTrayItem(Item As TrayItem)

Removes the passed item from the System Tray via the TrayItem class.


Application.ShowTooltip

ShowTooltip(tip As String, x As Integer, y As Integer, autoHide As Boolean)

Pops up the passed tip at the global coordinates given by x, y (relative to the screen). If AutoHide is True, then the tip will automatically hide itself; you do not have to call HideTooltip to hide it. The default is True.

AutoHide is used only on Windows and Linux; on macOS, the ToolTip hides automatically.

The following code is placed in the MouseDown event of a window. It uses the X and Y coordinates passed into the event.

App.ShowTooltip("This is my tip", Self.Left + X, Self.Top + Y)
Return True

The following code in the Action event of a PushButton displays the contents of a TextField as a tip.

App.ShowTooltip(TextField1.Text, System.MouseX, System.MouseY + 20)

Application.Window

Window(index As Integer) As Window

Returns a reference to an open window.

The Window function returns a reference to the window number passed. The window list contains all the windows that have been created. Window zero is the frontmost window. Floating windows are always in front of document windows. For example, to get the frontmost document window when you also have Floating windows, you must also check each window's Frame property. In evaluating the order of windows in the list from front to back, keep in mind that a window may not have its Visible property set to True. If this may be the case, check the Visible property of a window while identifying the frontmost visible window. If you don't, the code may identify the frontmost window as a window that is not Visible.

This function can be used in conjunction with the WindowCount function to loop through the open windows. Note that during a window's Open event, the window list includes that window, but during a window's Close event, the window list does not include that window.

If you pass in a window number that does not exist ( a value < 0 or >= WindowCount) then this function returns Nil.

This code places the titles of all open windows into a ListBox:

For i As Integer = App.WindowCount - 1 DownTo 0
  Var w As Window = App.Window(i)
  If w <> Nil Then
    ListBox1.AddRow(w.Title)
  End If
Next

This code gets the frontmost Document window. It considers only Document windows (Window.Type = Window.Types.Document) and takes into account the possibility that a window might not be visible:

Var frontmostDocumentWindow As Window
Var lastOffset As Integer = App.WindowCount - 1
For i As Integer = 0 To lastOffset
  Var w As Window = System.Window(i)
  If (w <> Nil) And (w.Type = Window.Types.Document) And w.Visible Then
    frontmostDocumentWindow = w
    Exit
  End If
Next
Return frontmostDocumentWindow

Event descriptions


Application.Activate

Activate

The app is being activated.

When the app is launched, the Open event is called prior to Activate.


Application.AppearanceChanged

AppearanceChanged

Called when a user switches between Light and Dark mode, when the accent color changes or on macOS when the user changes any accessibility system preferences that affect the appearance of the app.

Use this event to update any graphics or other UI as needed.

On macOS, you can use declares to determine which accessibility settings the user changed. Details on that can be found in Apple's documentation.


Application.CancelClose

CancelClose As Boolean

This event occurs first when the Application is about to terminate, e.g. if you used the Quit command or if the user chose Quit from the menu. Return True to cause the termination to stop.

This is the order in which events are called when a GUI Application initiates a termination process, i.e. when it quits: # CancelClose is called first. If, for any reason, you want to stop the termination process or interact with the user (use a modal window in such a case) to confirm, you should do it in this event. If you return True, the termination process will be stopped immediately. # Window.CancelClose is then called for each Window, one after the other. If any Window.CancelClose returns True, the termination process will be stopped. # Windows are all closed, one after the other. In the process, each Window event is called but you can no longer interrupt the termination process. # If you use asynchronous object like Thread event, it will be called. # The Close event is called.

Note that some objects can be destroyed (so their Destructor event called) after the Close event has been invoked.


Application.Close

Close

The app is quitting.

Close is called after CancelClose and after the window's CancelClose and Close events.

There is nothing you can do to abort the quitting process at that time. If you need to control if your app is allowed to quit in the current context, use CancelClose or Window.CancelClose.


Application.Deactivate

Deactivate

The app is being deactivated.

For example, this occurs when the user clicks on a window belonging to another app. When the user clicks on your app window again, the Activate event is called.


Application.EnableMenuItems

EnableMenuItems

Called when the user clicks in the menubar to give you the opportunity to determine which menu items to enable.

It also is called when the app opens if no default window is selected for the project and when the last window is closed.


Application.HandleAppleEvent

HandleAppleEvent(Event As AppleEvent, EventClass As String, EventID As String) As Boolean

An AppleEvent has been received.

Return True to accept the AppleEvent and False to reject it.

Intrinsic AppleEvents, such as "aevt/odoc", "aevt/quit", and "aevt/pref", are passed to this event handler first. If you return True, the default behavior will no longer take place. For example, if you return True for the "odoc" event, the OpenDocument event will not be called.


Application.NewDocument

NewDocument

The user launched the app by double-clicking the app icon or the NewDocument method was called.


Application.Open

Open

The app is opening.

The Open event is the first event called when your app starts.

The Activate event is called after the Open event.


Application.OpenDocument

OpenDocument(File As FolderItem)

The user has double-clicked on a document which this app is specified to open or the OpenDocument method was called.


Application.UnhandledException

UnhandledException(error As RuntimeException) As Boolean

If a RuntimeException is not caught anywhere else (using Exception or Try), this event is called so you may handle the exception. Return True to suppress the quit behavior. Return False to use the default quit behavior.

If a RuntimeException is not caught anywhere else, this event is called so you may handle the exception. See the example.

This code in the UnhandledException event of the App class catches any unhanded exceptions and displays the name of the exception along with the error stack:

If error <> Nil Then
  Var type As String = Introspection.GetType(error).Name
  MessageBox(type + EndOfLine + EndOfLine + String.FromArray(error.Stack, EndOfLine))
End If

Notes

Note

For web apps, refer to WebApplication. For console apps, refer to ConsoleApplication. For iOS apps, refer to MobileApplication.

A subclass of Application (called App) is automatically added when you create a new Desktop project. This new subclass gives you access to the Application class methods and events.

The App subclass has its own menu handlers which can be used to handle menu items when no windows are open or for menu items that should call the same menu handler regardless of which window is frontmost. You can change the global menubar by assigning a different menubar to its MenuBar property.

See the Control class for information on changing the cursor and adding cursors to your project.

The App function returns a reference to an instance of the subclass of Application in your project. See the App function for more information.

To change the app icon, click the Icon that is displayed in the Inspector when the App object is selected. Refer to App Icons for more information.


Adding additional application subclasses

If you wish, you can add additional subclasses based on the Application class to the project, but it is not necessary. If you do so, the one that is added to the project automatically is the one referred to by the App function and it is the one that will show the project's build settings.


Version information

If AutoIncrementVersionInformation is checked (a design-time property) then the NonReleaseVersion property is increased by one each time you do a build (but not when you run the project).

The compiler truncates version information when building Windows applications when the version information is too long to store into the executable file. The current byte limitations for these fields are as follows:

Field

Maximum length (bytes)

Long Version

79

Short Version

39

Package Info

253

Region

21

Release

11

Sample code

You can get the location of the folder in which the app is running, by getting the Parent of the executable file:

Var f as FolderItem
f = App.ExecutableFile.Parent

The following code in the Action event of a PushButton causes an OutofBoundsException runtime error when the counter, i, reaches the value of System.FontCount.

For i As Integer = 1 To FontCount
  ListBox1.AddRow(Font(i))
Next

Since there is no exception handler within the method, the runtime exception is passed up to the Application class, triggering the UnhandledException event.

This code in the UnhandledException event of the App class "catches" the unhandled OutOfBoundsException. Of course, it catches all unhandled OutOfBoundsExceptions throughout the Application, so it doesn't know where the error occurred. You could instead place an Exception statement within the PushButton's Action event so that you can provide more specific diagnostics.

Function UnhandledException(error As RuntimeException) As Boolean
  If error IsA OutOfBoundsException Then
    MessageBox("An OutOfBounds Exception error has occurred!")
  End If
  Return True
End Function

Compatibility

All project types on all supported operating systems.