SystemParametersInfo Function

Declare Function SystemParametersInfo Lib "user32.dll" Alias "SystemParametersInfoA" (ByVal uAction As Long, ByVal uiParam As Long, pvParam As Any, ByVal fWinIni As Long) As Long

Platforms: Win 32s, Win 95/98, Win NT

SystemParametersInfo reads or sets information about numerous settings in Windows. These include Windows's accessibility features as well as various settings for other things. The exact behavior of the function depends on the flag passed as uAction. All sizes and dimensions used by this function are measured in pixels. Whenever using a structure to receive information, the member identifying the size of the structure (if one exists) must be correctly set beforehand. Note that, when setting properties via this function, that the user may not expect such settings to be changed; normally only the Control Panel applets set many of these properties. The return value in almost all cases (there are exceptions, which are noted) is 0 if the function failed, or a non-zero value if the function succeeded. Note to Visual Basic users: Whenever passing a string as pvParam, must explictly add the ByVal keyword before it. This must also be done when explicitly setting the pvParam parameter to 0. See the examples for a demonstration of when and how this is done.

uAction

Exactly one of the following flags specifying the action taken by the function:

SPI_GETACCESSTIMEOUT = 60

Retrieve information about the time-out period associated with the accessibility features. uiParam must be the size of the ACCESSTIMEOUT structure. pvParam is an ACCESSTIMEOUT structure receiving the time-out settings.

SPI_GETANIMATION = 72

Win 95/98 only: Retrieve information about the animation effects associated with the user's actions. uiParam must be 0. pvParam is an ANIMATIONINFO structure receiving the animation effects settings.

SPI_GETBEEP = 1

Determine if the warning beeper is on or off. uiParam must be 0. pvParam is a Long-type variable which receives 0 if the warning beeper is off, or a non-zero value if it is on.

SPI_GETBORDER = 5

Retrieve the window sizing border multiplier factor, which determines the width of a window's sizing border. uiParam must be 0. pvParam is a Long-type variable which receives the current setting.

SPI_GETDEFAULTINPUTLANG = 89

Win 95/98 only: Retrieve a handle to the keyboard layout used for the system's default input language. uiParam must be 0. pvParam is a Long-type variable which receives the handle.

SPI_GETDRAGFULLWINDOWS = 38

Win 95/98 only: Determine if Windows displays the entire contents of a window when it is moved or resized (instead of merely displaying an outline of it). uiParam must be 0. pvParam is a Long-type variable which receives 0 if the contents are not displayed, or a non-zero value if they are.

SPI_GETFASTTASKSWITCH = 35

Determine if fast Alt-Tab task switching is enabled. uiParam must be 0. pvParam is a Long-type variable which receives 0 if fast task switching is not enabled, or a non-zero value if it is.

SPI_GETFILTERKEYS = 50

Retrieve the settings of the FilterKeys accessibility feature. uiParam must be the size of the FILTERKEYS structure. pvParam is a FILTERKEYS structure which receives the current settings of FilterKeys.

SPI_GETFONTSMOOTHING = 74

Determine whether font smoothing is enabled or not. uiParam must be 0. pvParam is a Long-type variable which receives 0 if font smoothing is not enabled, or a non-zero value if it is.

SPI_GETGRIDGRANULARITY = 18

Retrieve the current granularity of the desktop sizing grid. uiParam must be 0. pvParam is a Long-type variable which receives the current setting.

SPI_GETHIGHCONTRAST = 66

Win 95/98 only: Retrieve the settings of the HighContrast accessibility feature. uiParam must be 0. pvParam is a HIGHCONTRAST structure which receives the current settings of HighContrast.

SPI_GETICONMETRICS = 45

Win 95/98 only: Retrieve the metrics associated with icons, which determine how Windows displays icons. uiParam must be 0. pvParam is an ICONMETRICS structure which receives the icon metrics.

SPI_GETICONTITLELOGFONT = 31

Retrieve information about the logical font used to display the titles of icons. uiParam must be the size of the LOGFONT structure. pvParam is a LOGFONT structure which receives information about the logical font.

SPI_GETICONTITLEWRAP = 25

Determine if Windows word-wraps the text of icon titles. uiParam must be 0. pvParam is a Long-type variable which receives 0 if word-wrapping is not enabled, or a non-zero value if it is.

SPI_GETKEYBOARDDELAY = 22

Retrieve the current keyboard repeat delay setting, which is the time before a held key begins to repeat. uiParam must be 0. pvParam is a Long-type variable which receives the current delay setting (a value between 0 and 3).

SPI_GETKEYBOARDPREF = 68

Win 95/98 only: Determine if the user relies on the keyboard instead of the mouse and wants programs to display keyboard interfaces which are otherwise hidden. uiParam must be 0. pvParam is a Long-type variable which receives 0 if the user does not rely on the keyboard, or a non-zero value if the user does.

SPI_GETKEYBOARDSPEED = 10

Retrieve the current keyboard repeat speed setting, which is the speed between repeats when a key is held. uiParam must be 0. pvParam is a Long-type variable which receives the current speed setting (a value between 0 and 31).

SPI_GETLOWPOWERACTIVE = 83

Win 95/98 only: Determine if the system enters a low-power mode after a period of inactivity. uiParam must be 0. pvParam is a Long-type variable which receives 0 if low-power mode is not enabled, or a non-zero value if it is.

SPI_GETLOWPOWERTIMEOUT = 79

Win 95/98 only: Retrieve the time, in seconds, which must elapse before Windows enters low-power mode. uiParam must be 0. pvParam is a Long-type variable which receives the current timeout value.

SPI_GETMENUDROPALIGNMENT = 27

Determine if popup menus are left- or right-aligned. uiParam must be 0. pvParam is a Long-type variable which receives 0 if the menus are right-aligned, or a non-zero value if they are left-aligned.

SPI_GETMINIMIZEDMETRICS = 43

Win 95/98 only: Retrieve the metrics associated with minimized windows, which specify how Windows displays minimized windows. uiParam must be the size of the MINIMIZEDMETRICS structure. pvParam is a MINIMIZEDMETRICS structure which receives the minimized window metrics.

SPI_GETMOUSE = 3

Retrieve the x-axis and y-axis threshold values for the mouse as well as the mouse speed. uiParam must be 0. pvParam is a 3-element array of Long-type variables which receives the x-threshold, y-threshold, and mouse speed.

SPI_GETMOUSEKEYS = 54

Retrieve the settings of the MouseKeys accessibility feature. uiParam must be the size of the MOUSEKEYS structure. pvParam is a MOUSEKEYS structure which receives the current settings of MouseKeys.

SPI_GETMOUSETRAILS = 94

Win 95/98 only: Retrieve the current mouse trails setting. uiParam must be 0. pvParam receives 0 or 1 if mouse trails are not enabled, or a value greater than one identifying the number of cursor images making up the mouse trail.

SPI_GETNONCLIENTMETRICS = 41

Win 95/98 only: Retrieve the metrics associated with the nonclient areas of windows, which determine how Windows renders nonclient areas. uiParam must be 0. pvParam is a NONCLIENTMETRICS structure which receives the nonclient area metrics.

SPI_GETPOWEROFFACTIVE = 84

Win 95/98 only: Determine if the system enters a power-off mode after a period of inactivity. uiParam must be 0. pvParam is a Long-type variable which receives 0 if power-off mode is not enabled, or a non-zero value if power-off mode is enabled.

SPI_GETPOWEROFFTIMEOUT = 80

Win 95/98 only: Retrieve the time-out value, in seconds, that must elapse before Windows enters power-off mode. uiParam must be 0. pvParam is a Long-type variable which receives the time-out value for power-off mode.

SPI_GETSCREENREADER = 70

Win 95/98 only: Determine if a screen reader utility is running. If it is, applications should present more textual output instead of graphical output to help the reader function better. uiParam must be 0. pvParam is a Long-type variable which receives 0 if no screen reader is running, or a non-zero value if one is.

SPI_GETSCREENSAVEACTIVE = 16

Determine if a screen saver is set to run. uiParam must be 0. pvParam is a Long-type variable which receives 0 if no screen saver is set to run, or a non-zero value if one is.

SPI_GETSCREENSAVETIMEOUT = 14

Retrieve the time-out period, in seconds, which must elapse before the screen saver begins running. uiParam must be 0. pvParam is a Long-type variable which receives the time-out value.

SPI_GETSERIALKEYS = 62

Win 95/98 only: Retrieve the settings of the SerialKeys accessibility feature. uiParam must be 0. pvParam is a SERIALKEYS structure which receives the current settings of SerialKeys.

SPI_GETSHOWSOUNDS = 56

Determine if the user desires visual information to replace or suppliment otherwise audio-only output. uiParam must be 0. pvParam is a Long-type variable which receives 0 if programs should not display this added visual information, or a non-zero value if they should.

SPI_GETSOUNDSENTRY = 64

Retrieve the settings of the SoundSentry accessibility feature. uiParam must be the size of the SOUNDSENTRY structure. pvParam is a SOUNDSENTRY structure which receives the current settings of SoundSentry.

SPI_GETSTICKYKEYS = 58

Retrieve the settings of the StickyKeys accessibility feature. uiParam must be the size of the STICKYKEYS structure. pvParam is a STICKYKEYS structure which receives the settings of StickyKeys.

SPI_GETTOGGLEKEYS = 52

Retrieve the settings of the ToggleKeys accessibility feature. uiParam must be the size of the TOGGLEKEYS structure. pvParam is a TOGGLEKEYS structure which receives the current settings of ToggleKeys.

SPI_GETWINDOWSEXTENSION = 92

Win 95/98 only: Determine if the Windows extensions are installed. Win 95 requires that Microsoft Plus! be installed to get the extensions; the extensions are integrated as a part of Win 98. uiParam must be 1. pvParam must be 0. The function returns 0 if the extensions are disabled, or a non-zero value if they are enabled.

SPI_GETWORKAREA = 48

Win 95/98 only: Retrieve the size of the working area, which is a rectangle identifying the area of the desktop not obscured by the taskbar. uiParam must be 0. pvParam is a RECT structure which receives the rectangle of the working area.

SPI_ICONHORIZONTALSPACING = 13

Set the width of the icon spacing cell. uiParam is the new setting for the width. pvParam must be 0.

SPI_ICONVERTICALSPACING = 24

Set the height of the icon spacing cell. uiParam is the new setting for the height. pvParam must be 0.

SPI_LANGDRIVER = 12

Win 95/98 only: Retrieve the filename of the language driver. uiParam must be 0. pvParam is a String (with sufficient buffer space) which receives the filename of the language driver.

SPI_SETACCESSTIMEOUT = 61

Set information associated with the time-out period associated with the accessibility features. uiParam must be the size of the ACCESSTIMEOUT structure. pvParam is an ACCESSTIMEOUT structure holding the new time-out period settings.

SPI_SETANIMATION = 73

Win 95/98 only: Set information about the animation effects associated with the user's actions. uiParam must be 0. pvParam is an ANIMATIONINFO structure holding the new animation effects settings.

SPI_SETBEEP = 2

Turn the warning beeper on or off. uiParam is 0 to turn the beeper off, or a non-zero value to turn it on. pvParam must be 0.

SPI_SETBORDER = 6

Set the window sizing border multiplier factor, which determines the width of a window's sizing border. uiParam is the new setting. pvParam must be 0.

SPI_SETCURSORS = 87

Reload the images used for the system cursors. uiParam and pvParam must be 0.

SPI_SETDEFAULTINPUTLANG = 90

Win 95/98 only: Set the keyboard layout used for the system's default input language. uiParam is a handle to the keyboard layout to use. pvParam must be 0.

SPI_SETDESKPATTERN = 21

Set the current desktop pattern bitmap by causing Windows to reread the Pattern setting in the [Desktop] section of WIN.INI. Both uiParam and pvParam must be 0.

SPI_SETDESKWALLPAPER = 20

Set the current desktop wallpaper bitmap. uiParam must be 0. pvParam is a String holding the filename of the bitmap file to use as the wallpaper.

SPI_SETDOUBLECLICKTIME = 32

Set the time, in milliseconds, within which two successive mouse clicks must occur for Windows to interpret the input to be a double click. uiParam is the new double click time. pvParam must be 0.

SPI_SETDOUBLECLKHEIGHT = 30

Set the height of the rectangle within which two successive mouse clicks must occur for Windows to interpret the input to be a double click. uiParam is the new height. pvParam must be 0.

SPI_SETDOUBLECLKWIDTH = 29

Set the width of the rectangle within which two successive mouse clicks must occur for Windows to interpret the input to be a double click. uiParam is the new width. pvParam must be 0.

SPI_SETDRAGFULLWINDOWS = 37

Win 95/98 only: Turn dragging of full windows (displaying the contents of a window while moving or resizing instead of just an empty border) on or off. uiParam is 0 to turn dragging of full windows off, or a non-zero value to turn it on.

SPI_SETDRAGHEIGHT = 77

Win 95/98 only: Set the height of the rectangle which the cursor must move out of with a button depressed for Windows to begin a drag operation. uiParam is the new height. pvParam must be 0.

SPI_SETDRAGWIDTH = 76

Win 95/98 only: Set the width of the rectangle which the cursor must move out of with a button depressed for Windows to begin a drag operation. uiParam is the new width. pvParam must be 0.

SPI_SETFASTTASKSWITCH = 36

Turn fast Alt-Tab task switching on or off. uiParam is 0 to turn fast switching off, or a non-zero value to turn it on. pvParam must be 0.

SPI_SETFILTERKEYS = 51

Set the settings of the FilterKeys accessibility feature. uiParam must be the size of the FILTERKEYS structure. pvParam is a FILTERKEYS structure holding the new settings for FilterKeys.

SPI_SETFONTSMOOTHING = 75

Turn font smoothing on or off. uiParam is 0 to turn font smoothing off, or a non-zero value to turn it on.

SPI_SETGRIDGRANULARITY = 19

Set the granularity of the desktop sizing grid. uiParam is the new setting. pvParam must be 0.

SPI_SETHIGHCONTRAST = 67

Win 95/98 only: Set the settings of the HighContrast accessibility feature. uiParam must be 0. pvParam is a HIGHCONTRAST structure holding the new settings for HighContrast.

SPI_SETICONMETRICS = 46

Win 95/98 only: Set the metrics associated with icons, which specify how Windows displays icons. uiParam must be 0. pvParam is an ICONMETRICS structure holding the new icon metrics.

SPI_SETICONS = 88

Reload the images used for the system icons. uiParam and pvParam must be 0.

SPI_SETICONTITLELOGFONT = 34

Set the logical font used to display the text of icon titles. uiParam must be the size of the LOGFONT structure. pvParam is a LOGFONT structure holding the logical font to use.

SPI_SETICONTITLEWRAP = 26

Turn the word-wrapping of icon titles on or off. uiParam is 0 to turn word-wrapping off, or a non-zero value to turn it on. pvParam must be 0.

SPI_SETKEYBOARDDELAY = 23

Set the keyboard repeat-delay setting, which is the time that must elapse before a held key begins to repeat. uiParam is the new delay setting, between 0 and 3 inclusive. pvParam must be 0.

SPI_SETKEYBOARDPREF = 69

Win 95/98 only: Tell Windows whether the user depends on the keyboard as the main input device and wishes programs to display additional keyboard-based interfaces. uiParam is 0 to not indicate a keyboard preference, or a non-zero value to indicate one. pvParam must be 0.

SPI_SETKEYBOARDSPEED = 11

Set the keyboard repeat-speed setting, which specifies the rate at which keys are repeated. uiParam is the new speed setting, between 0 and 31 inclusive. pvParam must be 0.

SPI_SETLANGTOGGLE = 91

Win 95/98 only: Set the hot key used to switch keyboard input languages. The new value is read from the registry at HKEY_CURRENT_USER\keyboard layout\toggle: 1 sets the hot key to ALT+SHIFT, 2 sets the hot key to CTRL+SHIFT, and 3 disables the hot key. uiParam and pvParam must be 0.

SPI_SETLOWPOWERACTIVE = 85

Win 95/98 only: Turn the low-power mode after a period of inactivity on or off. uiParam is 0 to deactivate low-power mode, or 1 to activate to. pvParam must be 0.

SPI_SETLOWPOWERTIMEOUT = 81

Win 95/98 only: Set the time-out period (in seconds) which must elapse after user input before Windows enters low-power mode. uiParam is the new time-out period. pvParam must be 0.

SPI_SETMENUDROPALIGNMENT = 28

Set whether pop-up menus open to the left or to the right. uiParam is 0 if they open to the left, or a non-zero value if they open to the right. pvParam must be 0.

SPI_SETMINIMIZEDMETRICS = 44

Win 95/98 only: Set the metrics associated with minimized windows, which determine how Windows displays minimized windows. uiParam must be 0. pvParam is a MINIMIZEDMETRICS structure holding the new metrics.

SPI_SETMOUSE = 4

Set the x-axis and y-axis threshold values for the mouse as well as the mouse speed. uiParam must be 0. pvParam is a three-element Long-type array; the first element is the x-threshold, the second element is the y-threshold, and the third element is the mouse speed.

SPI_SETMOUSEBUTTONSWAP = 33

Swap or unswap the meanings of the left and right mouse buttons. uiParam is 0 to restore the left-to-left/right-to-right mapping, or a non-zero value to swap the buttons into a left-to-right/right-to-left mapping. pvParam must be 0.

SPI_SETMOUSEKEYS = 55

Set the settings of the MouseKeys accessibility feature. uiParam must be the size of the MOUSEKEYS structure. pvParam is a MOUSEKEYS structure holding the new settings for MouseKeys.

SPI_SETMOUSETRAILS = 93

Win 95/98 only: Set the length of the mouse trail. uiParam is 0 or 1 to turn mouse trails off, or a value greater than one identifying the number of cursor images used to make up the mouse trail. pvParam must be 0.

SPI_SETNONCLIENTMETRICS = 42

Win 95/98 only: Set the metrics associated with the non-client areas of windows, which determine how Windows displays the non-client areas. uiParam must be 0. pvParam is a NONCLIENTMETRICS structure holding the new metrics.

SPI_SETPENWINDOWS = 49

Win 95/98 only: Load or unload Microsoft Pen for Windows, if available. uiParam is 0 to unload Pen, or a non-zero value to load Pen. pvParam must be 0.

SPI_SETPOWEROFFACTIVE = 86

Win 95/98 only: Set whether the system powers down after a period of inactivity. uiParam is 0 to not enter power-off mode, or a non-zero value to enter power-off mode. pvParam must be 0.

SPI_SETPOWEROFFTIMEOUT = 82

Win 95/98 only: Set the time-out period, in seconds, which must elapse without user input before Windows enters power-off mode. uiParam is the new time-out period. pvParam must be 0.

SPI_SETSCREENREADER = 71

Win 95/98 only: Set whether a screen-reading program is currently running. uiParam is 0 if no reader is in use, or a non-zero value if one is. pvParam must be 0.

SPI_SETSCREENSAVEACTIVE = 17

Set whether Windows activates a screen saver after a period of inactivity. uiParam is 0 to turn the screen saver off, or a non-zero value to turn it on. pvParam must be 0.

SPI_SETSCREENSAVETIMEOUT = 15

Set the time-out period, in seconds, which must elapse before Windows launches a screen saver. uiParam is the new time-out period. pvParam must be 0.

SPI_SETSERIALKEYS = 63

Win 95/98 only: Set the settings of the SerialKeys accessibility feature. uiParam must be 0. pvParam is a SERIALKEYS structure holding the new settings for SerialKeys.

SPI_SETSHOWSOUNDS = 57

Turn the ShowSounds accessibility feature on or off. uiParam is 0 to turn ShowSounds off, or a non-zero value to turn ShowSounds on. pvParam must be 0.

SPI_SETSOUNDSENTRY = 65

Set the settings of the SoundSentry accessibility feature. uiParam must be the size of the SOUNDSENTRY structure. pvParam is a SOUNDSENTRY structure holding the new settings for SoundSentry.

SPI_SETSTICKYKEYS = 59

Set the settings of the StickyKeys accessibility feature. uiParam is the size of the STICKYKEYS structure. pvParam is a STICKYKEYS structure holding the new settings for StickyKeys.

SPI_SETTOGGLEKEYS = 53

Set the settings of the ToggleKeys accessibility feature. uiParam is the size of the TOGGLEKEYS structure. pvParam is a TOGGLEKEYS structure holding the new settings for ToggleKeys.

SPI_SETWORKAREA = 47

Win 95/98 only: Set the rectangle defining the working area of the desktop. The working area is the area of the desktop not obscured by the taskbar. uiParam must be 0. pvParam is a RECT structure holding the new working area rectangle.

uiParam

The purpose of this parameter varies with uAction.

pvParam

The purpose of this parameter varies with uAction. In VB, if this is to be set as a string or to 0, the ByVal keyword must preceed it.

fWinIni

Zero or more of the following flags specifying the change notification to take place. Generally, this can be set to 0 if the function merely queries information, but should be set to something if the function sets information.

SPIF_SENDWININICHANGE = &H2

Broadcast the change made by the function to all running programs.

SPIF_UPDATEINIFILE = &H1

Save the change made by the function to the user profile.

Example #1:

' Set the desktop wallpaper to the Clouds.bmp that comes with Windows.
' Note how the string passed to the function is preceeded by the ByVal keyword.
Dim windir As String  ' receives the path of the Windows directory
Dim cloudpath As String  ' filename of Clouds.bmp
Dim retval As Long  ' return value

' Get the path of the Windows directory.
windir = Space(255)  ' make room in the buffer
retval = GetWindowsDirectory(windir, 255)  ' get the path name
windir = Left(windir, InStr(windir, vbNullChar) - 1)  ' trim the null character and unused characters
cloudpath = windir & "Clouds.bmp"  ' add the filename to the path
' Set the Windows wallpaper, saving the change and notifying all programs
retval = SystemParametersInfo(SPI_SETDESKWALLPAPER, 0, ByVal cloudpath, SPIF_SENDWININICHANGE Or SPIF_UPDATEINIFILE)

Example #2:

' Tell the user whether the MouseKeys accessibility feature is on
' or off.  Note how the structure's cbSize parameter must be set first.
Dim mk As MOUSEKEYS  ' holds settings for MouseKeys
Dim retval As Long  ' return value

mk.cbSize = Len(mk)  ' set the size of the structure
' Load the MouseKeys settings into the structure.
retval = SystemParametersInfo(SPI_GETMOUSEKEYS, Len(mk), mk, 0)  ' don't need to notify
' Display whether MouseKeys is on or off.
If (mk.dwFlags And MKF_MOUSEKEYSON) = MKF_MOUSEKEYSON Then
  Debug.Print "MouseKeys is on."
Else
  Debug.Print "MouseKeys is off."
End If

See Also: GetSystemMetrics
Category: Accessibility

Go back to the alphabetical Function listing.
Go back to the Reference section index.

This page is copyright © 2000 Paul Kuliniewicz. Copyright Information.
Go back to the Windows API Guide home page.
E-mail: vbapi@vbapi.com Send Encrypted E-Mail
This page is at http://www.vbapi.com/ref/s/systemparametersinfo.html