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
- Refusing a request
- Properties
- Events
- SysACStatusConstants
- SysBatteryStatusConstants
- SysDeviceTypeConstants
- See Also
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
SystemParametersInfonames 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
intlfor the regional settings orEnvironmentfor 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