Class

# DesktopApplication

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

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

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

| Name                                                      | Type                                                             | Read-Only | Shared |
|-----------------------------------------------------------|------------------------------------------------------------------|-----------|--------|
| `AllowAutoQuit<desktopapplication.allowautoquit>`         | `Boolean</api/data_types/boolean>`                               |           |        |
| `AllowHiDPI<desktopapplication.allowhidpi>`               | `Boolean</api/data_types/boolean>`                               | ✓         |        |
| `BugVersion<desktopapplication.bugversion>`               | `Integer</api/data_types/integer>`                               | ✓         |        |
| `BuildDateTime<desktopapplication.builddatetime>`         | `DateTime</api/data_types/datetime>`                             | ✓         |        |
| `Copyright<desktopapplication.copyright>`                 | `String</api/data_types/string>`                                 | ✓         |        |
| `Description<desktopapplication.description_property>`    | `String</api/data_types/string>`                                 | ✓         |        |
| `DockItem<desktopapplication.dockitem>`                   | `DockItem</api/macos/dockitem>`                                  | ✓         |        |
| `ExecutableFile<desktopapplication.executablefile>`       | `FolderItem</api/files/folderitem>`                              | ✓         |        |
| `LastWindowIndex<desktopapplication.lastwindowindex>`     | `Integer</api/data_types/integer>`                               | ✓         |        |
| `MajorVersion<desktopapplication.majorversion>`           | `Integer</api/data_types/integer>`                               | ✓         |        |
| `MDIWindow<desktopapplication.mdiwindow>`                 | `DesktopMDIWindow</api/user_interface/desktop/desktopmdiwindow>` |           |        |
| `MenuBar<desktopapplication.menubar>`                     | `DesktopMenuBar</api/user_interface/desktop/desktopmenubar>`     |           |        |
| `MinorVersion<desktopapplication.minorversion>`           | `Integer</api/data_types/integer>`                               | ✓         |        |
| `MouseCursor<desktopapplication.mousecursor>`             | `MouseCursor</api/user_interface/desktop/mousecursor>`           |           |        |
| `NonReleaseVersion<desktopapplication.nonreleaseversion>` | `Integer</api/data_types/integer>`                               | ✓         |        |
| `ProcessID<desktopapplication.processid>`                 | `Integer</api/data_types/integer>`                               | ✓         |        |
| `RegionCode<desktopapplication.regioncode>`               | `Integer</api/data_types/integer>`                               | ✓         |        |
| `StageCode<desktopapplication.stagecode>`                 | `Integer</api/data_types/integer>`                               | ✓         |        |
| `Version<desktopapplication.version>`                     | `String</api/data_types/string>`                                 | ✓         |        |

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                                | Parameters                                                                                                                                                                | Returns                                                    | Shared |
|-----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------|--------|
| `AddTrayItem<desktopapplication.addtrayitem>`       | item As `TrayItem</api/user_interface/desktop/desktoptrayitem>`                                                                                                           | `Boolean</api/data_types/boolean>`                         |        |
| `DoEvents<desktopapplication.doevents>`             | milliseconds As `Integer</api/data_types/integer>` = -1                                                                                                                   |                                                            |        |
| `HideTooltip<desktopapplication.hidetooltip>`       |                                                                                                                                                                           |                                                            |        |
| `NewDocument<desktopapplication.newdocument>`       |                                                                                                                                                                           |                                                            |        |
| `OpenDocument<desktopapplication.opendocument>`     | file As `FolderItem</api/files/folderitem>`                                                                                                                               |                                                            |        |
| `RefreshMenuBar<desktopapplication.refreshmenubar>` |                                                                                                                                                                           |                                                            |        |
| `RemoveTrayItem<desktopapplication.removetrayitem>` | item As `DesktopTrayItem</api/user_interface/desktop/desktoptrayitem>`                                                                                                    |                                                            |        |
| `ShowTooltip<desktopapplication.showtooltip>`       | tip As `String</api/data_types/string>`, x As `Integer</api/data_types/integer>`, y As `Integer</api/data_types/integer>`, autoHide As `Boolean</api/data_types/boolean>` |                                                            |        |
| `WindowAt<desktopapplication.windowat>`             | index As `Integer</api/data_types/integer>`                                                                                                                               | `DesktopWindow</api/user_interface/desktop/desktopwindow>` |        |
| `WindowCount<desktopapplication.windowcount>`       |                                                                                                                                                                           | `Integer</api/data_types/integer>`                         |        |
| `Windows<desktopapplication.windows>`               |                                                                                                                                                                           | `Iterable</api/language/iterable>`                         |        |

## Events

<div class="rst-class">

table-centered_column_4

</div>

| Name                                                        | Parameters                                                                                                                                   | Returns                            |
|-------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| `Activated<desktopapplication.activated>`                   |                                                                                                                                              |                                    |
| `AppearanceChanged<desktopapplication.appearancechanged>`   |                                                                                                                                              |                                    |
| `AppleEventReceived<desktopapplication.appleeventreceived>` | theEvent As `AppleEvent</api/macos/appleevent>`, eventClass As `String</api/data_types/string>`, eventID As `String</api/data_types/string>` | `Boolean</api/data_types/boolean>` |
| `CancelClosing<desktopapplication.cancelclosing>`           |                                                                                                                                              | `Boolean</api/data_types/boolean>` |
| `Closing<desktopapplication.closing>`                       |                                                                                                                                              |                                    |
| `Deactivated<desktopapplication.deactivated>`               |                                                                                                                                              |                                    |
| `DocumentCreated<desktopapplication.documentcreated>`       |                                                                                                                                              |                                    |
| `DocumentOpened<desktopapplication.documentopened>`         | item As `FolderItem</api/files/folderitem>`                                                                                                  |                                    |
| `MenuBarSelected<desktopapplication.menubarselected>`       |                                                                                                                                              |                                    |
| `Opening<desktopapplication.opening>`                       |                                                                                                                                              |                                    |
| `UnhandledException<desktopapplication.unhandledexception>` | error As `RuntimeException</api/exceptions/runtimeexception>`                                                                                | `Boolean</api/data_types/boolean>` |

## 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

<div id="desktopapplication.allowautoquit">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.AllowAutoQuit

**AllowAutoQuit** As `Boolean</api/data_types/boolean>`

> When `True</api/language/true>`, the application quits when the last window is closed, whether by calling the Close method of the `Window</api/user_interface/desktop/desktopwindow>` class or by the user closing the last window manually.
>
> AllowAutoQuit defaults to `True</api/language/true>` on non-MDI Windows applications and `True</api/language/true>` on Linux. It defaults to `False</api/language/false>` on MDI Windows and macOS applications.
>
> This code is in the `Opening<desktopapplication.opening>` event of the App class.
>
> ``` xojo
> App.AllowAutoQuit = True
> ```

<div id="desktopapplication.allowhidpi">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.AllowHiDPI

**AllowHiDPI** As `Boolean</api/data_types/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</api/language/true>` by default.
>
> This property is read-only.
>
> You can read this property at runtime:
>
> ``` xojo
> 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:
>
> ``` xojo
> 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:
>
> ``` xojo
> 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 = rm.SubExpressionString(1).CDbl
>     p.HorizontalResolution = 72 * n
>     p.VerticalResolution = 72 * n
>   End If
> End Sub
> ```

<div id="desktopapplication.bugversion">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.BugVersion

**BugVersion** As `Integer</api/data_types/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).
>
> <div class="note">
>
> <div class="title">
>
> Note
>
> </div>
>
> On Windows valid values are between 0 to 255.
>
> </div>
>
> Puts all the individual versions together to create the full version:
>
> ``` xojo
> Var fullVersion As String
> fullVersion = App.MajorVersion.ToString + "." + App.MinorVersion.ToString + "." _
>   + App.BugVersion.ToString + "." + App.NonReleaseVersion.ToString.
> ```

<div id="desktopapplication.builddatetime">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.BuildDateTime

**BuildDateTime** As `DateTime</api/data_types/datetime>`

> Contains the date and time when the application was built.
>
> You can also access the `CreationDateTime<folderitem.creationdatetime>` property of the application's `FolderItem</api/files/folderitem>` by calling App.ExecutableFile.CreationDate.
>
> This property is read-only.
>
> The following code gets the build date/time and displays it in a `Label</api/user_interface/desktop/desktoplabel>`.
>
> ``` xojo
> Var d As DateTime
> d = App.BuildDateTime
>
> Label1.Text = d.ToString
> ```

<div id="desktopapplication.copyright">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.Copyright

**Copyright** As `String</api/data_types/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:
>
> ``` xojo
> MessageBox(App.Copyright)
> ```

<div id="desktopapplication.description_property">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.Description

**Description** As `String</api/data_types/string>`

> A text description for the app that will appear in the Windows Desktop Explorer Properties window.
>
> This property is read-only.
>
> This property can be set only in the IDE.

<div id="desktopapplication.dockitem">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.DockItem

**DockItem** As `DockItem</api/macos/dockitem>`

> Enables you to manipulate the dock item associated with the application (macOS only).
>
> This property is read-only.
>
> The DockItem property enables you to access the properties and methods of the `DockItem</api/macos/dockitem>` class. This class has two methods, UpdateNow and ResetIcon, and one property, Graphics. Use the methods of the `Graphics</api/graphics/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 `Graphics.ClearRectangle<graphics.clearrectangle>` method to start over from a blank icon. Anything you can do with a `Graphics</api/graphics/graphics>` object you are able to do with the Dock's Graphics object (like drawing in a picture or using a `Group2D</api/graphics/group2d>`). The DockItem property of the `DesktopWindow</api/user_interface/desktop/desktopwindow>` class enables you to control the dock item for individual windows.

<div id="desktopapplication.executablefile">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.ExecutableFile

**ExecutableFile** As `FolderItem</api/files/folderitem>`

> Returns a `FolderItem</api/files/folderitem>` for the actual executable application even if it is in a bundle.
>
> This property is read-only.
>
> Application.ExecutableFile returns `Nil</api/language/nil>` if the app has been deleted or an error occurs finding it.
>
> Use the properties and methods of the `FolderItem</api/files/folderitem>` class to get/set attributes of the executable file and/or perform operations. For example:
>
> ``` xojo
> Var appPath As String
> appPath = App.ExecutableFile.NativePath
> ```
>
> gets the full path to the executable.
>
> ``` xojo
> 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<folderitem.parent>` of the executable file:
>
> ``` xojo
> Var f As FolderItem
> f = App.ExecutableFile.Parent
> ```

<div id="desktopapplication.lastwindowindex">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.LastWindowIndex

**LastWindowIndex** As `Integer</api/data_types/integer>`

> Returns the index of the last window the app opened.
>
> This property is read-only.

<div id="desktopapplication.majorversion">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.MajorVersion

**MajorVersion** As `Integer</api/data_types/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).
>
> This value appears in the Properties window of the Desktop Explorer on Windows but does not appear in the Get Info window on MacOS or on Linux.
>
> <div class="note">
>
> <div class="title">
>
> Note
>
> </div>
>
> On Windows valid values are between 0 to 255.
>
> </div>
>
> Puts all the individual versions together to create the full version:
>
> ``` xojo
> Var fullVersion As String
> fullVersion = App.MajorVersion.ToString + "." + App.MinorVersion.ToString + "." _
>   + App.BugVersion.ToString + "." + App.NonReleaseVersion.ToString.
> ```

<div id="desktopapplication.mdiwindow">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.MDIWindow

**MDIWindow** As `DesktopMDIWindow</api/user_interface/desktop/desktopmdiwindow>`

> Provides access to the properties and methods of the `DesktopMDIWindow</api/user_interface/desktop/desktopmdiwindow>` 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.
>
> ``` xojo
> App.MDIWindow.Title = "The MDI Window Title"
> ```

<div id="desktopapplication.menubar">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.MenuBar

**MenuBar** As `DesktopMenuBar</api/user_interface/desktop/desktopmenubar>`

> 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<desktopwindow.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 Opening 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.
>
> ``` xojo
> App.MenuBar = MenuBar2
> ```

<div id="desktopapplication.minorversion">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.MinorVersion

**MinorVersion** As `Integer</api/data_types/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).
>
> This value appears in the Properties window of the Desktop Explorer on Windows but does not appear in the Get Info window on MacOS or on Linux.
>
> <div class="note">
>
> <div class="title">
>
> Note
>
> </div>
>
> On Windows valid values are between 0 to 255.
>
> </div>
>
> Puts all the individual versions together to create the full version:
>
> ``` xojo
> Var fullVersion As String
> fullVersion = App.MajorVersion.ToString + "." + App.MinorVersion.ToString + "." _
>   + App.BugVersion.ToString + "." + App.NonReleaseVersion.ToString.
> ```

<div id="desktopapplication.mousecursor">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.MouseCursor

**MouseCursor** As `MouseCursor</api/user_interface/desktop/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</api/language/nil>`, the non-Nil MouseCursor properties belonging to any `Window</api/user_interface/desktop/desktopwindow>` or `Control</api/user_interface/desktop/desktopuicontrol>` are ignored.
>
> You can use the cursors in the `Cursors</api/user_interface/desktop/cursors>` module to set the mouse cursor.
>
> This line in the Opening event of the App class sets the default cursor to the finger pointer.
>
> ``` xojo
> App.MouseCursor = System.Cursors.FingerPointer
> ```

<div id="desktopapplication.nonreleaseversion">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.NonReleaseVersion

**NonReleaseVersion** As `Integer</api/data_types/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.
>
> This value appears in the Properties window of the Desktop Explorer on Windows but does not appear in the Get Info window on MacOS or on Linux.
>
> <div class="note">
>
> <div class="title">
>
> Note
>
> </div>
>
> On Windows valid values are between 0 to 255.
>
> </div>
>
> 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:
>
> ``` xojo
> Var fullVersion As String
> fullVersion = App.MajorVersion.ToString + "." + App.MinorVersion.ToString + "." _
>   + App.BugVersion.ToString + "." + App.NonReleaseVersion.ToString.
> ```

<div id="desktopapplication.processid">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.ProcessID

**ProcessID** As `Integer</api/data_types/integer>`

> Returns the system process ID for the app that you would see in something like Activity Monitor (macOS) or Task Manager (Windows).
>
> This property is read-only.

<div id="desktopapplication.regioncode">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.RegionCode

**RegionCode** As `Integer</api/data_types/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.

<div id="desktopapplication.stagecode">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.StageCode

**StageCode** As `Integer</api/data_types/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       |
>
> This value appears in the Properties window of the Desktop Explorer on Windows but does not appear in the Get Info window on MacOS or on Linux.

<div id="desktopapplication.version">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.Version

**Version** As `String</api/data_types/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:
>
> ``` xojo
> MessageBox(App.Version)
> ```

## Method descriptions

<div id="desktopapplication.addtrayitem">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.AddTrayItem

**AddTrayItem**(item As `DesktopTrayItem</api/user_interface/desktop/desktoptrayitem>`) As `Boolean</api/data_types/boolean>`

> Adds the passed *item* to the System Tray via the `DesktopTrayItem</api/user_interface/desktop/desktoptrayitem>` class.
>
> AddTrayItem returns a `Boolean</api/data_types/boolean>` that indicates success or failure. If it returns `True</api/language/true>`, the `DesktopTrayItem</api/user_interface/desktop/desktoptrayitem>` was added successfully. The System Tray is supported on Windows and Linux only. See the `DesktopTrayItem</api/user_interface/desktop/desktoptrayitem>` class.

<div id="desktopapplication.doevents">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.DoEvents

**DoEvents**(milliseconds As `Integer</api/data_types/integer>` = -1)

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

<div id="desktopapplication.hidetooltip">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.HideTooltip

**HideTooltip**

> Hides the tooltip. Call this if the *AutoHide* parameter of the `ShowTooltip<desktopapplication.showtooltip>` method was `False</api/language/false>`.
>
> Call this if you had passed `False</api/language/false>` to the corresponding call to `ShowTooltip<desktopapplication.showtooltip>` or you are not programming for macOS and need to hide the tooltip manually.
>
> ``` xojo
> App.HideTooltip
> ```

<div id="desktopapplication.newdocument">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.NewDocument

**NewDocument**

> Calls the `DocumentCreated<desktopapplication.documentcreated>` event handler.

<div id="desktopapplication.opendocument">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.OpenDocument

**OpenDocument**(item As `FolderItem</api/files/folderitem>`)

> Calls the `DocumentOpened<desktopapplication.documentopened>` event handler.

<div id="desktopapplication.refreshmenubar">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.RefreshMenuBar

**RefreshMenuBar**

> Forces an update of the menu bar and calls `MenuBarSelected<desktopapplication.menubarselected>` 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 SelectionChanged event handler of a `TextField</api/user_interface/desktop/desktoptextfield>` 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 MenuBarSelected event handlers on <span class="title-ref">DesktopApplication</span>, `Window</api/user_interface/desktop/desktopwindow>`, `Container</api/user_interface/desktop/desktopcontainer>` and `MenuItem</api/user_interface/desktop/desktopmenuitem>`.
>
> ``` xojo
> App.RefreshMenuBar
> ```

<div id="desktopapplication.removetrayitem">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.RemoveTrayItem

**RemoveTrayItem**(item As `DesktopTrayItem</api/user_interface/desktop/desktoptrayitem>`)

> Removes the passed *item* from the System Tray via the `DesktopTrayItem</api/user_interface/desktop/desktoptrayitem>` class.

<div id="desktopapplication.showtooltip">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.ShowTooltip

**ShowTooltip**(tip As `String</api/data_types/string>`, x As `Integer</api/data_types/integer>`, y As `Integer</api/data_types/integer>`, autoHide As `Boolean</api/data_types/boolean>`)

> Pops up the passed *tip* at the global coordinates given by *x*, *y* (relative to the screen). If *autoHide* is `True</api/language/true>`, then the *tip* will automatically hide itself; you do not have to call `HideTooltip<desktopapplication.hidetooltip>` to hide it. The default is `True</api/language/true>`.
>
> *autoHide* is used only on Windows and Linux; on macOS, the ToolTip hides automatically.
>
> The following code is placed in the `MouseDown<desktopwindow.mousedown>` event of a `window</api/user_interface/desktop/desktopwindow>`. It uses the *X* and *Y* coordinates passed into the event.
>
> ``` xojo
> App.ShowTooltip("This is my tip", Self.Left + X, Self.Top + Y)
> Return True
> ```
>
> The following code in the `Pressed<desktopbutton.pressed>` event of a `DesktopButton</api/user_interface/desktop/desktopbutton>` displays the contents of a `DesktopTextField</api/user_interface/desktop/desktoptextfield>` as a tip.
>
> ``` xojo
> App.ShowTooltip(TextField1.Text, System.MouseX, System.MouseY + 20)
> ```

<div id="desktopapplication.windowat">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.WindowAt

**WindowAt**(index As `Integer</api/data_types/integer>`) As `DesktopWindow</api/user_interface/desktop/desktopwindow>`

> 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</api/language/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<desktopapplication.windowcount>` function to loop through the open windows. Note that during a window's `Opening<desktopwindow.opening>` event, the window list includes that window, but during a window's `Closing<desktopwindow.closing>` 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<desktopapplication.windowcount>`) then this function returns `Nil</api/language/nil>`.
>
> <div class="warning">
>
> <div class="title">
>
> Warning
>
> </div>
>
> This function returns only DesktopWindows. Windows of the original Window class will not be returned.
>
> </div>
>
> This code places the titles of all open windows into a `DesktopListBox</api/user_interface/desktop/desktoplistbox>`:
>
> ``` xojo
> For i As Integer = App.WindowCount - 1 DownTo 0
>   Var w As DesktopWindow = App.WindowAt(i)
>   If w <> Nil Then
>     ListBox1.AddRow(w.Title)
>   End If
> Next
> ```
>
> This code gets the frontmost Document window. It considers only Document windows (`DesktopWindow.Types.Document<desktopwindow.types>`) and takes into account the possibility that a window might not be visible:
>
> ``` xojo
> Var frontmostDocumentWindow As DesktopWindow
> Var lastOffset As Integer = App.WindowCount - 1
> For i As Integer = 0 To lastOffset
>   Var w As DesktopWindow = App.WindowAt(i)
>   If (w <> Nil) And (w.Type = DesktopWindow.Types.Document) And w.Visible Then
>     frontmostDocumentWindow = w
>     Exit
>   End If
> Next
> Return frontmostDocumentWindow
> ```

<div id="desktopapplication.windowcount">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.WindowCount

**WindowCount** As `Integer</api/data_types/integer>`

> Returns the number of open windows.
>
> The WindowCount property includes any windows that are invisible. If called during a window's `Opening<desktopwindow.opening>` event, it includes that window. If called during a window's `Closing<desktopwindow.closing>` event, it does not include that window.
>
> <div class="warning">
>
> <div class="title">
>
> Warning
>
> </div>
>
> This function returns only the number of DesktopWindows. Windows of the original Window class will not be included in the number returned.
>
> </div>

<div id="desktopapplication.windows">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.Windows

**Windows** As `Iterable</api/language/iterable>`

> Allows you to iterate through all the open windows.

## Event descriptions

<div id="desktopapplication.activated">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.Activated

**Activated**

> The app is being activated.
>
> When the app is launched, the Opening event is called prior to Activated.

<div id="desktopapplication.appearancechanged">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.AppearanceChanged

**AppearanceChanged**

> Called when a user switches between Light and Dark mode or when the accent color changes.
>
> Use this event to update any graphics or other UI as needed.

<div id="desktopapplication.appleeventreceived">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.AppleEventReceived

**AppleEventReceived**(theEvent As `AppleEvent</api/macos/appleevent>`, eventClass As `String</api/data_types/string>`, eventID As `String</api/data_types/string>`) As `Boolean</api/data_types/boolean>`

> An `AppleEvent</api/macos/appleevent>` has been received.
>
> `Return</api/language/return>` `True</api/language/true>` to accept the `AppleEvent</api/macos/appleevent>` and `False</api/language/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</api/language/true>`, the default behavior will no longer take place. For example, if you return `True</api/language/true>` for the "odoc" event, the DocumentOpened event will not be called.

<div id="desktopapplication.cancelclosing">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.CancelClosing

**CancelClosing** As `Boolean</api/data_types/boolean>`

> This event occurs first when the application is about to terminate, e.g. if you used the `Quit</api/language/quit>` command or if the user chose *Quit* from the menu. Return `True</api/language/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:
>
> 1.  `CancelClosing<desktopapplication.cancelclosing>` 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</api/language/true>`, the termination process will be stopped immediately.
> 2.  `DesktopWindow.CancelClosing<desktopwindow.cancelclosing>` is then called for each `DesktopWindow</api/user_interface/desktop/desktopwindow>`, one after the other. If **any** `DesktopWindow.CancelClosing<desktopwindow.cancelclosing>` returns `True</api/language/true>`, the termination process will be stopped.
> 3.  Windows are all closed, one after the other. In the process, each `Window</api/user_interface/desktop/desktopwindow>` event is called but you can no longer interrupt the termination process.
> 4.  If you use asynchronous object like `` Thread</api/language/threading/thread>`s, :doc:`Timer</api/language/timer>`s or sockets, they are terminated by the runtime environment then destroyed even if the runtime did not or could not stop them. If such objects are subclasses and have a :doc:`Destructor</api/language/destructor> `` event, it will be called.
> 5.  The `Closing<desktopapplication.closing>` event is called.
>
> <div class="note">
>
> <div class="title">
>
> Note
>
> </div>
>
> Some objects can be destroyed (so their `Destructor</api/language/destructor>` event called) **after** the `Closing<desktopapplication.closing>` event has been invoked.
>
> </div>

<div id="desktopapplication.closing">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.Closing

**Closing**

> The app is quitting.
>
> `Closing<desktopapplication.closing>` is called after `CancelClosing<desktopapplication.cancelclosing>` and after the window's `CancelClosing<desktopwindow.cancelclosing>` and `Closing<desktopwindow.closing>` 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 `CancelClosing<desktopapplication.cancelclosing>` or `DesktopWindow.CancelClosing<desktopwindow.cancelclosing>`.

<div id="desktopapplication.deactivated">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.Deactivated

**Deactivated**

> 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 Activated event is called.

<div id="desktopapplication.documentcreated">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.DocumentCreated

**DocumentCreated**

> The user launched the app by double-clicking the app icon or the `NewDocument<desktopapplication.newdocument>` method was called.

<div id="desktopapplication.documentopened">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.DocumentOpened

**DocumentOpened**(item As `FolderItem</api/files/folderitem>`)

> The user has double-clicked on a document which this app is specified to open or the `OpenDocument<desktopapplication.opendocument>` method was called.
>
> This code loads the text of the supplied file into a TextArea on Window1:
>
> ``` xojo
> If item <> Nil Then
>   Var input As TextInputStream
>   input = TextInputStream.Open(item)
>
>   Var w As New Window1
>   w.TextArea1.Text = input.ReadAll
>   w.Show
>
>   input.Close
> End If
> ```

<div id="desktopapplication.menubarselected">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.MenuBarSelected

**MenuBarSelected**

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

<div id="desktopapplication.opening">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.Opening

**Opening**

> The app is opening.
>
> The Opening event is the first event called when your app starts.
>
> The `Activated<desktopapplication.activated>` event is called after the Opening event.

<div id="desktopapplication.unhandledexception">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DesktopApplication.UnhandledException

**UnhandledException**(error As `RuntimeException</api/exceptions/runtimeexception>`) As `Boolean</api/data_types/boolean>`

> If a `RuntimeException</api/exceptions/runtimeexception>` is not caught anywhere else (using `Exception</api/exceptions/exception>` or `Try</api/language/try>`), this event is called so you may handle the exception. Return `True</api/language/true>` to suppress the quit behavior. Return `False</api/language/false>` to use the default quit behavior.
>
> If a `RuntimeException</api/exceptions/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:
>
> ``` xojo
> If error <> Nil Then
>   Var type As String = Introspection.GetType(error).Name
>   MessageBox(type + EndOfLine + EndOfLine + String.FromArray(error.Stack, EndOfLine))
> End If
> ```

## Notes

<div class="note">

<div class="title">

Note

</div>

For web apps, refer to `WebApplication</api/web/webapplication>`. For console apps, refer to `ConsoleApplication</api/console/consoleapplication>`. For iOS apps, refer to `MobileApplication</api/mobile/mobileapplication>`.

</div>

A subclass of <span class="title-ref">DesktopApplication</span> (called App) is automatically added when you create a new Desktop project. This new subclass gives you access to the <span class="title-ref">DesktopApplication</span> 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 `DesktopControl</api/user_interface/desktop/desktopcontrol>` class for information on changing the cursor and adding cursors to your project.

The `App</api/language/app>` function returns a reference to an instance of the subclass of <span class="title-ref">DesktopApplication</span> in your project. See the `App</api/language/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</topics/application_structure/app_icons>` for more information.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Adding additional <span class="title-ref">DesktopApplication</span> subclasses

If you wish, you can add additional subclasses based on the <span class="title-ref">DesktopApplication</span> 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</api/language/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<folderitem.parent>` of the executable file:

``` xojo
Var f As FolderItem
f = App.ExecutableFile.Parent
```

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

The following code in the Pressed event of a `DesktopButton</api/user_interface/desktop/desktopbutton>` causes an `OutofBoundsException</api/exceptions/outofboundsexception>` runtime error when the counter, i, reaches the value of `System.FontCount<system.fontcount>`.

``` xojo
For i As Integer = 1 To System.FontCount
  ListBox1.AddRow(System.FontAt(i))
Next
```

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Since there is no exception handler within the method, the runtime exception is passed up to the <span class="title-ref">DesktopApplication</span> class, triggering the UnhandledException event.

This code in the UnhandledException event of the App class "catches" the unhandled `OutOfBoundsException</api/exceptions/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 `DesktopButton</api/user_interface/desktop/desktopbutton>`'s Pressed event so that you can provide more specific diagnostics.

``` xojo
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

|                       |         |
|-----------------------|---------|
| **Project Types**     | Desktop |
| **Operating Systems** | All     |

<div class="seealso">

`Object</api/data_types/additional_types/object>` parent class; `App</api/language/app>`, `System</api/os/system>`, objects; `AppleEvent</api/macos/appleevent>`, `ConsoleApplication</api/console/consoleapplication>`, `DesktopMDIWindow</api/user_interface/desktop/desktopmdiwindow>`, `ServiceApplication</api/console/serviceapplication>`, `WebApplication</api/web/webapplication>`, `MobileApplication</api/mobile/mobileapplication>` classes.

</div>