Module

System

Description

The properties of the System module are used to get information about the computer running the application.

Methods

Name

Parameters

Returns

Shared

Beep

DebugLog

msg As String

Device

DeviceData

DismissKeyboard

EnvironmentVariable

Name As String

String

FontAt

index As Integer

String

GotoMap

address As String

GotoURL

URL As String

IsFunctionAvailable

FunctionName As String, LibraryName As String

Boolean

Log

Level As Integer, msg As String

Microseconds

Double

NetworkInterface

index As Integer = -1

NetworkInterface

Random

Random

Speak

phrase As String, allowInterrupt As Boolean

Ticks

Integer

Version

System.VersionData

Property descriptions

System.CommandLine

CommandLine As String

This property contains the parameters passed to the application.

This property is read-only.

For example, if the application "Foo.exe" was executed with the call "Foo.exe a b c", then CommandLine would contain "Foo.exe a b c". This is valid for Windows, macOS, and Linux applications.

Note

CommandLine is not supported for Mobile projects.

System.Cursors

Cursors As MouseCursor

Provides access to the cursors in the Cursors module.

This property is read-only.

Use these cursors to change the current mouse pointer to any of the standard cursor shapes.

Note

Cursors is only supported for Desktop projects.

The following line in the MouseDown event of a Canvas changes the cursor to the HandClosed cursor. Returning True allows the MouseUp event to be called.

Me.MouseCursor = System.Cursors.HandOpen
Return True

System.FontCount

FontCount As Integer

Used to determine the number of fonts installed on the user's computer.

This property is read-only.

FontCount is useful when you need to build a list of available fonts or need to determine if a specific font is installed.

This example populates a top-level menu called FontMenu with the names of the installed fonts:

For i As Integer = 0 To System.FontCount - 1
  FontMenu.AddMenu(New MenuItem(System.FontAt(i)))
Next

System.Keychain

Keychain As Keychain

Returns the default Keychain.

This property is read-only.

You can assign the default Keychain by setting this to another Keychain. If no Keychain exists, it will try to create one. If you don't want it to create one, you should first call System.KeyChainCount and check against 0.

Note

Keychain is supported for only Desktop projects on macOS.

The following example adds a KeychainItem for an application and assigns a password.

Var newItem As KeychainItem
If System.KeychainCount > 0 Then
  newItem = New KeychainItem
  ' Indicate the name of the application
  newItem.ServiceName = "MyApplication"

  ' Create a new keychain item for the application and assign the password
  System.Keychain.AddPassword(newItem, "SecretPassword")
Else
  System.Beep
  MessageBox("You don't have a key chain.")
End If

Exception e As KeychainException
  MessageBox("Can't add item: " + e.Message)

System.KeychainCount

KeychainCount As Integer

Returns the number of available Keychains.

This property is read-only.

This number includes all Keychains within the Keychains folder as well as any other Keychains known to the Keychain's manager.

Note

KeychainCount is supported for only Desktop projects on macOS.

The following example adds a KeychainItem for an application and assigns a password. It first checks to make sure that there are some keychain items.

Var newItem As KeychainItem
If System.KeychainCount > 0 Then
  newItem = New KeychainItem
  ' Indicate the name of the application
  newItem.ServiceName = "MyApplication"

  ' Create a new keychain item for the application and assign the password
  System.KeyChain.AddPassword(newItem, "SecretPassword")
Else
  System.Beep
  MessageBox("You don't have a key chain.")
End If

Exception e As KeychainException
  MessageBox("Can't add item: " + e.Message)

System.LastFontIndex

LastFontIndex As Integer

The index number of the last font installed on the user's computer.

This property is read-only.

This example populates a top-level menu called FontMenu with the names of the installed fonts:

For i As Integer = 0 To System.LastFontIndex
  FontMenu.AddMenu(New MenuItem(System.FontAt(i)))
Next

System.MouseDown

MouseDown As Boolean

True if the mouse button has been pressed.

This property is read-only.

Note

MouseDown is supported for Desktop projects only.

System.MouseX

MouseX As Integer

The X coordinate of the mouse (points). Measured from the top-left corner of the screen.

This property is read-only.

Note

MouseX is supported for Desktop projects only.

This example gives the X and Y coordinates of the mouse when an event fires. For example, it works in a MouseDown or MouseEnter control event handler.

MessageBox("X=" + System.MouseX.ToString + " Y=" + System.MouseY.ToString)

System.MouseY

MouseY As Integer

The Y coordinate of the mouse (points). Measured from the top-left corner of the screen.

This property is read-only.

Note

MouseY is supported for Desktop projects only.

This example gives the X and Y coordinates of the mouse when an event fires. For example, it works in a MouseDown or MouseEnter event.

MessageBox("X=" + System.MouseX.ToString + " Y=" + System.MouseY.ToString)

System.Network

Network As Network

Provides access to the methods of the Network module. They enable you to verify whether the computer is connected to a network and, if so, to look up DNS and IP addresses.

This property is read-only.

Note

Network is not supported for mobile projects.

The following call returns the IP address for the wikipedia.org domain name.

Var ipAddress As String
ipAddress = System.Network.LookupIPAddress("wikipedia.org")
If Not ipAddress.IsEmpty Then
  MessageBox(ipAddress)
Else
  MessageBox("An error occurred.")
End If

System.NetworkInterfaceCount

NetworkInterfaceCount As Integer

Returns the count of NetworkInterfaces on the computer that are actually connected to a network.

This property is read-only.

This example lists the IP addresses of the network interfaces on the computer:

Var count As Integer
count = System.NetworkInterfaceCount

For i As Integer = 0 To count - 1
  Listbox1.AddRow(System.NetworkInterface(i).IPAddress)
Next

System.WebCursors

WebCursors As MouseCursor

Provides access to the cursors in the WebCursors module.

This property is read-only.

Use these cursors to change the current mouse pointer to any of the standard cursor shapes.

Note

WebCursors is supported for Web projects only.

The following code changes the pointer to a Finger Pointer when it is moved into the region of the control.

Me.Cursor = System.WebCursors.FingerPointer
Return True

Method descriptions

System.Beep

Beep

Plays the default System alert sound.

The Beep method plays the default Beep sound selected on your computer.

Note

This method is not supported for Mobile projects.

This code beeps if an error occurs:

Var isError As Boolean = True
If isError Then
  System.Beep
End If

System.DebugLog

DebugLog(msg As String)

Outputs msg to the System debug log.

On Windows, it logs to the debugger, so programs like DebugView can be used to view the string. On macOS, it logs to the Console. On Linux, it prints the message to StdErr.

You can also view DebugLog output using the Messages panel in Xojo which is displayed by clicking the Messages icon at the bottom of the Xojo workspace window.

System.Device

Device As DeviceData

Returns a DeviceData object (singleton) that provides information about the device such as battery level, orientation, model name, etc.

This example displays the device's model name:

MessageBox(System.Device.Model)

System.DismissKeyboard

DismissKeyboard

Hides the on-screen keyboard.

Note

This method is only supported for Android.

System.EnvironmentVariable

EnvironmentVariable(Name As String) As String

Used to get and set environment variables. Name is case-sensitive.

For web applications, you can use this method to get the "ROOT" or "DOCUMENT_ROOT" environment variables used by the web server. The "env" example below can be used to list all the available environment variables on your web server.

Note

EnvironmentVariable is not supported for mobile projects.

Get the value of the HOME environment variable:

Var s As String
s = System.EnvironmentVariable("HOME")

MessageBox(s)

Set the value of the HOME environment variable:

System.EnvironmentVariable("HOME") = "/Users/*username*"

To get the list of environment variables and their values (macOS and Linux), execute the "env" command from a terminal window or via the Shell class. On Windows, use the "set" command instead of "env".

Var sh As New Shell
Var cmd As String
#If TargetWindows Then
  cmd = "set"
#Else
  cmd = "env"
#EndIf

sh.Execute(cmd)
TextArea1.Text = sh.Result

This example gets the value of the COMPUTERNAME environment variable on Windows.

#If TargetWindows Then
  TextField1.Text = System.EnvironmentVariable("COMPUTERNAME")
#EndIf

System.FontAt

FontAt(index As Integer) As String

Used to access the names the installed fonts.

This is a function that determines if the font named passed is installed on the user's computer:

Function FontAvailable(FontName As String) As Boolean
   For i As Integer = 0 To System.LastFontIndex
    If System.FontAt(i) = FontName Then
      Return True
    End If
  Next
  Return False
End Function

System.GotoMap

GotoMap(address As String)

Launches Google Maps passing it the address passed.

Note

This method is only supported for Android.

System.GotoURL

GotoURL(URL As String)

Uses the appropriate web browser application (based on the user's Internet settings) to go to the HTTP URL specified.

Displays the supplied URL in the user's default web browser. If the browser is not open, it will launch the browser. Whether the URL opens in a new tab or a new window is controlled by the user's browser settings.

GotoURL is not global in a web app so you need to use WebControl instead.

A URL is an address for Internet locations such as web sites, FTP and email addresses.

When used in a web app, if a web URL is passed, the current page is replaced with the page at the URL passed.

Some web browsers have a limit on the length of a URL. These are common prefixes:

URL Prefix

Type

Notes

http://

web site

Displays in the default web browser.

mailto:

email

Opens the default email client with the supplied email address filled in.

ftp://

file transfer protocol

Opens the default FTP application to download the specified file.

This desktop code launches the user's chosen web browser and go to the Xojo web page.

System.GotoURL("http://www.xojo.com")

This desktop code launches the user's chosen FTP client application and go to an FTP site.

System.GotoURL("ftp://ftp.mysite.com/uploads")

This desktop code launches the user's chosen email application and create a new email message, with the specified email address in the "To" area.

System.GotoURL("mailto:diana@themyscira.org")

System.IsFunctionAvailable

IsFunctionAvailable(FunctionName As String, LibraryName As String) As Boolean

IsFunctionAvailable will attempt to load the passed function from the specified library.

If the function can be loaded, IsFunctionAvailable returns True. If the operation fails, it returns False. Calling IsFunctionAvailable or using the Soft keyword in a Declare statement will cache both the library loading code as well as the function itself. Multiple calls to the same function will suffer almost no overhead costs in comparison to regular ("hard") Declares. See the description of Soft Declares in the notes for the Declare statement.

Note

IsFunctionAvailable is not supported for mobile projects.

System.Log

Log(Level As Integer, msg As String)

Writes msg to the logging mechanism.

On macOS and Linux, it writes to the System logger, which is typically at /var/log. On Windows it writes to the Event Logger, which can be viewed by the Event Viewer.

Note

Log is not supported for Mobile projects.

Note

On macOS, the following levels do not appear in the log: debug, information, and success. This is an macOS issue.

For debugging purposes, use System.DebugLog instead.

Use the following class constants when setting the value of the Level parameter in calls to the Log method.

Constant

LogLevelAlert

LogLevelCritical

LogLevelDebug

LogLevelEmergency

LogLevelError

LogLevelInformation

LogLevelNotice

LogLevelSuccess

LogLevelWarning

For the following example writes your error message with the LogLevelError constant.

System.Log(System.LogLevelError, "my Error message")

System.Microseconds

Microseconds As Double

Returns the number of microseconds (1,000,000th of a second) that have passed since the user's device was started.

Because modern operating systems can stay running for so long, it's possible for the device's internal counters to "roll over." This means that if you are using this function to determine how much time has elapsed, you may encounter a case where this time is inaccurate.

The machine's internal counters might or might not continue to advance while the machine is asleep, or in a similar power-saving mode. Therefore, this function might not be suitable for use as a long-term timer.

This code displays in message box the number of minutes the device has been on:

Var minutes As Integer
minutes = System.Microseconds / 1000000 / 60
MessageBox("Your device has been on for " + minutes.ToString + " minutes.")

System.NetworkInterface

NetworkInterface(index As Integer = -1) As NetworkInterface

Use the NetworkInterface object to obtain networking information about the user's computer.

Use the optional parameter to specify the network interface card. If Index is out of bounds, an OutOfBoundsException is raised. NetworkInterfaceCount gives you the number of network interfaces in the computer.

The following simple example displays the IP address, Subnet mask, and Mac address for the selected network interface. At start-up, the application detects all the network interfaces installed on the user's computer and loads them into a PopupMenu. The user then selects the desired network interface and the values are displayed in TextFields.

The PopupMenu's Opening event handler is:

For i As Integer = 0 To System.NetworkInterfaceCount - 1
  PopupMenu1.AddRow(i.ToString)
Next

The SelectionChanged event handler for the PopupMenu is this:

Sub SelectionChanged()
  If Me.SelectedRowIndex > -1 Then
    ' Get the NetworkInterface object for the selected item
    Var iface As NetworkInterface = System.NetworkInterface(Me.SelectedRowIndex)
    MacAddressField.Text = iface.MACAddress
    IPAddressField.Text = iface.IPAddress
    SubnetMaskField.Text = iface.SubnetMask
  End If
End Sub

System.Random

Random As Random

Returns the singleton instance of the Random class for generating random numbers.

System.Speak

Speak(phrase As String, allowInterrupt As Boolean)

Uses the built-in speech synthesizer to pronounce the passed text string.

Speak takes a string (or any variant that can be expressed as a string) and uses the Windows or Macintosh text-to-speech engine to speak the text. The speech is asynchronous, allowing normal program flow to continue. By default, subsequent calls to Speak before the first call has finished will queue up and speak after the completion of the previous call. If the optional interrupt flag is used and set to True, the previous Speak calls will be stopped immediately.

On Linux, Speak uses the eSpeak library which is installed by default on Ubuntu 10.04 and newer.

Note

Speak is only supported for Desktop and Mobile projects.

The following code in a DesktopButton pronounces the phrase entered into a DesktopTextField.

If Not TextField1.Text.IsEmpty Then
  System.Speak(TextField1.Text)
Else
  System.Speak("Please enter some text in the field!")
End If

System.Ticks

Ticks As Integer

Returns the length of time in ticks (60th of a second) that the device has been running since it was last booted. Note that this does not include time while the device is asleep.

Because modern operating systems can stay running for a very long time, it's possible for the device's internal counter to reach its maximum value and then return to zero to begin counting again. This means that if you are using this function to determine how much time has elapsed between two events, you may encounter a case where it appears that the stop time is prior to the start time.

This code displays in message box the number of minutes the device has been on.

Var minutes As Integer
minutes = System.Ticks / 60 / 60
MessageBox("Your device has been on for " + minutes.ToString + " minutes.")

System.Version

Version As System.VersionData

Information about the current OS System version.

  • Can compare against text numbers formatted as "Major.Minor.Patch".

If System.Version >= "10.14.1" Then

  • Automatically adds "0" to any missing segments. "14" is changed to "14.0.0" before the comparison is done.

  • Use System.VersionData to display the OS version.

Notes

MouseX and MouseY return coordinates with respect to the top-left corner of the user's monitor. The DesktopWindow class contains MouseX and MouseY properties that are referenced to the window.

Multiple interface support

Multiple network interface support enables you to write applications that can bind to different NIC cards installed on a user's machine. For example, you can use this to write tunneling applications. To see what interfaces are installed on the user's machine, you can use the GetNetworkInterface method and assign the obtained interface object to a NetworkInterface property of the SocketCore class.

Compatibility

All project types on all supported operating systems.