Module
System
Description
The properties of the System module are used to get information about the computer running the application.
Properties
Name |
Type |
Read-Only |
Shared |
---|---|---|---|
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
Methods
Name |
Parameters |
Returns |
Shared |
---|---|---|---|
msg As String |
|||
Name As String |
|||
index As Integer |
|||
address As String |
|||
URL As String |
|||
index As Integer = -1 |
|||
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
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.CoreCount
CoreCount As Integer
Returns the total number of logical cores the CPU has.
Note
This method is not currently supported for Android.
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.
Note
This method is only supported for mobile projects.
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 |
---|---|---|
web site |
Displays in the default web browser. |
|
mailto: |
Opens the default email client with the supplied email address filled in. |
|
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 NetworkInterface method and assign the obtained interface object to a NetworkInterface property of the SocketCore class.
Compatibility
All project types on all supported operating systems.
See also
DesktopApplication, MouseCursor; App, Cursors, NetworkInterface objects.