SysInfo class

A SysInfo is a control that shows nothing at run time: it raises events when the settings, the devices or the power of the system change, and its properties report the power status, the desktop’s work area and the width of a scroll bar.

Debug.Print TypeName(SysInfo1.WorkAreaWidth)
Debug.Print SysInfo1.WorkAreaWidth > 0
Debug.Print SysInfo1.WorkAreaLeft >= 0, SysInfo1.WorkAreaTop >= 0
' Output:
' Single
' True
' True          True

The control stands in place of the SysInfo control of SYSINFO.OCX, and adds the ThemeChanged event and the hMain property.

Of the common members, the control has Name, Parent and Tag alone.

How the events arrive

Windows tells each top-level window of a program when a setting of the system changes, by a window message: WM_SETTINGCHANGE for a setting, WM_TIMECHANGE for the clock, WM_DEVICECHANGE for a device, WM_POWERBROADCAST for the power. The control watches the messages of the top-level window that its form belongs to, hMain, and raises an event for each. It also asks Windows for the arrival and removal of every kind of device interface, and raises DeviceArrival and the other device events for those too.

A program that wants to see its handler work can send such a message to hMain itself, which changes nothing on the system:

Dim Watch As New SettingsWatcher
Set Watch.Info = SysInfo1
SysInfoSendMessage SysInfo1.hMain, WM_TIMECHANGE, 0, 0
Dim Section As String = "intl"
SysInfoSendMessage SysInfo1.hMain, WM_SETTINGCHANGE, 0, StrPtr(Section)
' Output:
' TimeChanged
' SettingChanged 0 intl

SettingsWatcher in this sample is a class of the program’s own that holds the control WithEvents and prints its events.

Refusing a request

DeviceQueryRemove, QueryChangeConfig and PowerQuerySuspend are raised when Windows asks whether the program agrees to a change. A handler that sets Cancel to True refuses it: the control answers Windows with BROADCAST_QUERY_DENY. Windows 10 sends no request before the system sleeps, so PowerQuerySuspend and PowerQuerySuspendFailed are not raised there; PowerSuspend and PowerResume are.

Private Sub SysInfo1_DeviceQueryRemove(ByVal DeviceType As SysDeviceTypeConstants, ByVal DeviceID As Long, ByVal DeviceName As String, ByVal DeviceData As Long, Cancel As Boolean)
    ' Keep drive E: while the program still writes to it.
    If DeviceType = SysDeviceTypeVolume And DeviceName = "E" Then Cancel = DriveEInUse
End Sub

Properties

Every property of the control is read-only: assigning one raises run-time error 383.

ACStatus

Whether the computer runs on mains power. A member of SysACStatusConstants.

BatteryFullTime

How long a full battery lasts, in seconds. Long. It is -1 when Windows does not know, and while the computer is on mains power.

BatteryLifePercent

The charge left in the battery, as a percentage from 0 to 100. Integer. It is 255 when Windows does not know.

BatteryLifeTime

How long the charge left in the battery lasts, in seconds. Long. It is -1 when Windows does not know, and while the computer is on mains power.

BatteryStatus

The state of the battery’s charge: the sum of the members of SysBatteryStatusConstants that apply, such as SysBatteryStatusHigh and SysBatteryStatusCharging. It is 0 for a battery between low and high that is not charging.

hMain

The handle of the window whose messages the control watches: the top-level window at the end of the chain of parents and owners of the control’s own window. LongPtr.

ScrollBarSize

The width of a vertical scroll bar, in twips. Single.

WorkAreaHeight, WorkAreaLeft, WorkAreaTop, WorkAreaWidth

The size and the position of the work area of the primary monitor, the part of its desktop that the taskbar does not cover, in twips. Single.

Events

ConfigChangeCancelled, ConfigChanged

Raised when a change of the hardware profile, such as docking or undocking a laptop, has been cancelled and when it has been made.

Syntax: object_ConfigChanged( )

DeviceArrival, DeviceRemoveComplete

Raised when a device or a medium has been added to the system, such as a USB drive plugged in or a disc put in a drive, and when one has been removed.

Syntax: object_DeviceArrival( ByVal DeviceType As SysDeviceTypeConstants, ByVal DeviceID As Long, ByVal DeviceName As String, ByVal DeviceData As Long )

DeviceType
The kind of device, a member of SysDeviceTypeConstants. The arguments that follow depend on it, as the table there says.
DeviceID, DeviceName, DeviceData
What identifies the device: for a volume, the drives as a mask with one bit for each letter, the first letter, and 1 for a medium or 2 for a network drive.

A volume’s DeviceID has bit 0 for drive A, bit 3 for drive D and so on, and DeviceName is the letter of its lowest bit.

DeviceQueryRemove

Raised when Windows asks whether a device may be removed. See Refusing a request.

Syntax: object_DeviceQueryRemove( ByVal DeviceType As SysDeviceTypeConstants, ByVal DeviceID As Long, ByVal DeviceName As String, ByVal DeviceData As Long, Cancel As Boolean )

DeviceType, DeviceID, DeviceName, DeviceData
As in DeviceArrival.
Cancel
False when the event is raised. A handler that sets it to True refuses the removal.

DeviceQueryRemoveFailed, DeviceRemovePending

Raised when the removal of a device has been refused, by this program or another, and when the device is about to be removed, after every program has agreed.

Syntax: object_DeviceRemovePending( ByVal DeviceType As SysDeviceTypeConstants, ByVal DeviceID As Long, ByVal DeviceName As String, ByVal DeviceData As Long )

The arguments are as in DeviceArrival.

DevModeChanged

Raised when the settings of a printer have changed.

Syntax: object_DevModeChanged( )

DevNodesChanged

Raised when a device has been added to the system or removed from it. A program that keeps a list of devices reads it again.

Syntax: object_DevNodesChanged( )

DisplayChanged

Raised when the resolution or the color depth of the screen has changed.

Syntax: object_DisplayChanged( ByVal NewColorDepth As Long, ByVal NewWidth As Single, ByVal NewHeight As Single )

NewColorDepth
The bits for each pixel.
NewWidth, NewHeight
The size of the screen, in twips.

The size is the screen’s size in pixels times Screen.TwipsPerPixelX and TwipsPerPixelY.

FontChanged

Raised when a font has been installed or removed.

Syntax: object_FontChanged( )

PowerQuerySuspend

Raised when Windows asks whether the system may sleep. See Refusing a request.

Syntax: object_PowerQuerySuspend( Cancel As Boolean )

Cancel
False when the event is raised. A handler that sets it to True refuses the request.

PowerQuerySuspendFailed

Raised when the system was to sleep and a program refused it.

Syntax: object_PowerQuerySuspendFailed( )

PowerResume

Raised when the system has woken from sleep.

Syntax: object_PowerResume( )

PowerStatusChanged

Raised when the power status has changed: the computer has been plugged in or unplugged, or the battery’s charge has changed. The properties then report the new status.

Syntax: object_PowerStatusChanged( )

PowerSuspend

Raised just before the system sleeps.

Syntax: object_PowerSuspend( )

QueryChangeConfig

Raised when Windows asks whether the hardware profile may change. See Refusing a request.

Syntax: object_QueryChangeConfig( Cancel As Boolean )

SettingChanged

Raised when a setting of the system has changed, by the user in the Settings app or by a program.

Syntax: object_SettingChanged( ByVal Item As Long, ByVal Section As String )

Item
The number of the setting, as the Windows function SystemParametersInfo names it, such as 47 (SPI_SETWORKAREA) when the work area has changed. It is 0 for a change that is not one of those.
Section
The name of the part of the settings that changed, such as intl for the regional settings or Environment for the environment variables, or empty.

SysColorsChanged

Raised when a system color has changed.

Syntax: object_SysColorsChanged( )

ThemeChanged

Raised when a visual style of Windows has been turned on or off, or another one chosen.

Syntax: object_ThemeChanged( )

TimeChanged

Raised when the system time has been changed.

Syntax: object_TimeChanged( )

SysACStatusConstants

The values of ACStatus.

Member Value Description
SysACStatusOffline 0 The computer runs on its battery.
SysACStatusOnline 1 The computer runs on mains power.
SysACStatusUnknown 255 Windows does not know.

SysBatteryStatusConstants

The flags of BatteryStatus.

Member Value Description
SysBatteryStatusHigh 1 More than 66 per cent of the charge is left.
SysBatteryStatusLow 2 Less than 33 per cent is left.
SysBatteryStatusCritical 4 Less than 5 per cent is left.
SysBatteryStatusCharging 8 The battery is charging.
SysBatteryStatusNone 128 The computer has no battery.
SysBatteryStatusUnknown 255 Windows does not know.

SysDeviceTypeConstants

The values of the DeviceType argument of the device events, and what the other arguments then hold.

Member Value Device DeviceID DeviceName DeviceData
SysDeviceTypeOEM 0 A device of the computer’s maker its identifier empty its function
SysDeviceTypeDevNode 1 A node of the device tree the node empty 0
SysDeviceTypeVolume 2 A drive the drives, one bit for each letter the first letter 1 for a medium, 2 for a network drive
SysDeviceTypePort 3 A serial or parallel port 0 its name, such as COM3 0
SysDeviceTypeDevInterface 5 A device interface 0 the interface’s path 0

See Also

  • Common members – the three common members this control has
  • Screen object – the size of the whole screen, and the twips in a pixel