DesktopApplication


Description

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

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


DesktopApplication.AllowAutoQuit

AllowAutoQuit As Boolean

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

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

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

App.AllowAutoQuit = True

DesktopApplication.AllowHiDPI

AllowHiDPI As Boolean

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

This property is read-only.

You can read this property at runtime:

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

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

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

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

Use the text "False" to turn it off.

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

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

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

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

DesktopApplication.BugVersion

BugVersion As Integer

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

This property is read-only.

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

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

Note

On Windows valid values are between 0 to 255.

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

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

DesktopApplication.BuildDateTime

BuildDateTime As DateTime

Contains the date and time when the application was built.

This property is read-only.

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

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

Var d As DateTime
d = App.BuildDateTime

Label1.Text = d.ToString

DesktopApplication.Copyright

Copyright As String

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

This property is read-only.

Display the copyright info:

MessageBox(App.Copyright)

DesktopApplication.Description

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


DesktopApplication.DockItem

DockItem As DockItem

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

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

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

  • Call the UpdateNow method to redraw the icon.

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


DesktopApplication.ExecutableFile

ExecutableFile As FolderItem

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

This property is read-only.

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

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

Var appPath As String
appPath = App.ExecutableFile.NativePath

gets the full path to the executable.

Var cd As DateTime
cd = App.ExecutableFile.CreationDateTime

gets the date/time the executable was created.

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

Var f As FolderItem
f = App.ExecutableFile.Parent

DesktopApplication.LastWindowIndex

LastWindowIndex As Integer

Returns the index of the last window the app opened.

This property is read-only.


DesktopApplication.MajorVersion

MajorVersion As Integer

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

This property is read-only.

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

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

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.

Note

On Windows valid values are between 0 to 255.

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

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

DesktopApplication.MDIWindow

MDIWindow As MDIWindow

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

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

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

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

DesktopApplication.MenuBar

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

App.MenuBar = MenuBar2

DesktopApplication.MinorVersion

MinorVersion As Integer

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

This property is read-only.

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

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

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.

Note

On Windows valid values are between 0 to 255.

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

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

DesktopApplication.MouseCursor

MouseCursor As MouseCursor

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

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

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

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

App.MouseCursor = System.Cursors.FingerPointer

DesktopApplication.NonReleaseVersion

NonReleaseVersion As Integer

The version you increment each time you build your project.

This property is read-only.

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

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

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

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

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.

Note

On Windows valid values are between 0 to 255.

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

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

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

DesktopApplication.RegionCode

RegionCode As Integer

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

This property is read-only.


DesktopApplication.StageCode

StageCode As Integer

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

This property is read-only.

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

Value

Description

0

Development

1

Alpha

2

Beta

3

Final

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.


DesktopApplication.Version

Version As String

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

This property is read-only.

Typically version numbers are written as 1.2.3.4.

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

Display the short version:

MessageBox(App.Version)

Method descriptions


DesktopApplication.AddTrayItem

AddTrayItem(item As DesktopTrayItem) As Boolean

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

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


DesktopApplication.DoEvents

DoEvents(milliseconds As Integer = -1)

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


DesktopApplication.HideTooltip

HideTooltip

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

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

App.HideTooltip

DesktopApplication.NewDocument

NewDocument

Calls the DocumentCreated event handler.


DesktopApplication.OpenDocument

OpenDocument(File As FolderItem)

Calls the DocumentOpened event handler.


DesktopApplication.RefreshMenuBar

RefreshMenuBar

Forces an update of the menu bar and calls 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 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 DesktopApplication, Window, Container and MenuItem.

App.RefreshMenuBar

DesktopApplication.RemoveTrayItem

RemoveTrayItem(item As DesktopTrayItem)

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


DesktopApplication.ShowTooltip

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

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

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

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

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

The following code in the Pressed event of a DesktopButton displays the contents of a DesktopTextField as a tip.

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

DesktopApplication.WindowAt

WindowAt(index As Integer) As 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. If this may be the case, check the Visible property of a window while identifying the frontmost visible window. If you don't, the code may identify the frontmost window as a window that is not Visible.

This function can be used in conjunction with the WindowCount function to loop through the open windows. Note that during a window's Opening event, the window list includes that window, but during a window's 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) then this function returns Nil.

Warning

This function returns only DesktopWindows. Windows of the original Window class will not be returned.

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

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) and takes into account the possibility that a window might not be visible:

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

DesktopApplication.WindowCount

WindowCount As Integer

Returns the number of open windows.

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

Warning

This function returns only the number of DesktopWindows. Windows of the original Window class will not be included in the number returned.


DesktopApplication.Windows

Windows As Iterable

Allows you to iterate through all the open windows.

Event descriptions


DesktopApplication.Activated

Activated

The app is being activated.

When the app is launched, the Opening event is called prior to Activated.


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.


DesktopApplication.AppleEventReceived

AppleEventReceived(theEvent As AppleEvent, eventClass As String, eventID As String) As Boolean

An AppleEvent has been received.

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

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


DesktopApplication.CancelClosing

CancelClosing As Boolean

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

This is the order in which events are called when a GUI application initiates a termination process, i.e. when it quits:

  1. 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, the termination process will be stopped immediately.

  2. DesktopWindow.CancelClosing is then called for each DesktopWindow, one after the other. If any DesktopWindow.CancelClosing returns True, the termination process will be stopped.

  3. Windows are all closed, one after the other. In the process, each Window event is called but you can no longer interrupt the termination process.

  4. If you use asynchronous object like Thread event, it will be called.

  5. The Closing event is called.

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


DesktopApplication.Closing

Closing

The app is quitting.

Closing is called after CancelClosing and after the window's CancelClosing and 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 or DesktopWindow.CancelClosing.


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.


DesktopApplication.DocumentCreated

DocumentCreated

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


DesktopApplication.DocumentOpened

DocumentOpened(item As FolderItem)

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

This code loads the text of the supplied file into a TextArea on Window1:

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

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.


DesktopApplication.Opening

Opening

The app is opening.

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

The Activated event is called after the Opening event.


DesktopApplication.UnhandledException

UnhandledException(error As RuntimeException) As Boolean

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

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

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

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

Notes

Note

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

A subclass of DesktopApplication (called App) is automatically added when you create a new Desktop project. This new subclass gives you access to the DesktopApplication 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 class for information on changing the cursor and adding cursors to your project.

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

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


Adding additional DesktopApplication subclasses

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


Version information

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

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

Field

Maximum length (bytes)

Long Version

79

Short Version

39

Package Info

253

Region

21

Release

11

Sample code

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

Var f as FolderItem
f = App.ExecutableFile.Parent

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

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 DesktopApplication class, triggering the UnhandledException event.

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

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

Compatibility

Desktop projects on all supported operating systems.