SystemParametersInfoA function (winuser.h) - Win32 apps (original) (raw)

Important

Some information relates to a prerelease product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Retrieves or sets the value of one of the system-wide parameters. This function can also update the user profile while setting a parameter.

Syntax

BOOL SystemParametersInfoA(
  [in]      UINT  uiAction,
  [in]      UINT  uiParam,
  [in, out] PVOID pvParam,
  [in]      UINT  fWinIni
);

Parameters

[in] uiAction

Type: UINT

The system-wide parameter to be retrieved or set. The possible values are organized in the following tables of related parameters:

• Accessibility parameters
• Desktop parameters
• Icon parameters
• Input parameters
• Menu parameters
• Power parameters
• Screen saver parameters
• Time-out parameters
• UI effect parameters
• Window parameters

The following are the accessibility parameters.

The following are the desktop parameters.

The following are the icon parameters.

The following are the input parameters. They include parameters related to the keyboard, mouse, touchpad, pen, input language, and the warning beeper.

The following are the menu parameters.

The following are the power parameters.

Beginning with Windows Server 2008 and Windows Vista, these power parameters are not supported. Instead, to determine the current display power state, an application should register for GUID_MONITOR_POWER_STATE notifications. To determine the current display power down time-out, an application should register for notification of changes to the GUID_VIDEO_POWERDOWN_TIMEOUT power setting. For more information, see Registering for Power Events.

Windows Server 2003 and Windows XP/2000: To determine the current display power state, use the following power parameters.

The following are the screen saver parameters.

The following are the time-out parameters for applications and services.

The following are the UI effects. The SPI_SETUIEFFECTS value is used to enable or disable all UI effects at once. This table contains the complete list of UI effect values.

The following are the window parameters.

[in] uiParam

Type: UINT

A parameter whose usage and format depends on the system parameter being queried or set. For more information about system-wide parameters, see the uiAction parameter. If not otherwise indicated, you must specify zero for this parameter.

[in, out] pvParam

Type: PVOID

A parameter whose usage and format depends on the system parameter being queried or set. For more information about system-wide parameters, see the uiAction parameter. If not otherwise indicated, you must specify NULL for this parameter. For information on the PVOID datatype, see Windows Data Types.

[in] fWinIni

Type: UINT

If a system parameter is being set, specifies whether the user profile is to be updated, and if so, whether the WM_SETTINGCHANGE message is to be broadcast to all top-level windows to notify them of the change.

This parameter can be zero if you do not want to update the user profile or broadcast the WM_SETTINGCHANGE message, or it can be one or more of the following values.

Return value

Type: BOOL

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

This function is intended for use with applications that allow the user to customize the environment.

A keyboard layout name should be derived from the hexadecimal value of the language identifier corresponding to the layout. For example, U.S. English has a language identifier of 0x0409, so the primary U.S. English layout is named "00000409". Variants of U.S. English layout, such as the Dvorak layout, are named "00010409", "00020409" and so on. For a list of the primary language identifiers and sublanguage identifiers that make up a language identifier, see the MAKELANGID macro.

There is a difference between the High Contrast color scheme and the High Contrast Mode. The High Contrast color scheme changes the system colors to colors that have obvious contrast; you switch to this color scheme by using the Display Options in the control panel. The High Contrast Mode, which uses SPI_GETHIGHCONTRAST and SPI_SETHIGHCONTRAST, advises applications to modify their appearance for visually-impaired users. It involves such things as audible warning to users and customized color scheme (using the Accessibility Options in the control panel). For more information, see HIGHCONTRAST. For more information on general accessibility features, see Accessibility.

During the time that the primary button is held down to activate the Mouse ClickLock feature, the user can move the mouse. After the primary button is locked down, releasing the primary button does not result in a WM_LBUTTONUP message. Thus, it will appear to an application that the primary button is still down. Any subsequent button message releases the primary button, sending a WM_LBUTTONUP message to the application, thus the button can be unlocked programmatically or through the user clicking any button.

This API is not DPI aware, and should not be used if the calling thread is per-monitor DPI aware. For the DPI-aware version of this API, see SystemParametersInfoForDPI. For more information on DPI awareness, see the Windows High DPI documentation.

Examples

The following example uses SystemParametersInfo to double the mouse speed.

#include <windows.h>
#include <stdio.h>
#pragma comment(lib, "user32.lib")    

void main()  
{     
    BOOL fResult;
    int aMouseInfo[3];    // Array for mouse information
    
    // Get the current mouse speed.         
    fResult = SystemParametersInfo(SPI_GETMOUSE,   // Get mouse information
                                   0,              // Not used
                                   &aMouseInfo,    // Holds mouse information
                                   0);             // Not used           
                                   
    // Double it.         
    if( fResult )     
    {
        aMouseInfo[2] = 2 * aMouseInfo[2];
        
        // Change the mouse speed to the new value.
        SystemParametersInfo(SPI_SETMOUSE,      // Set mouse information
                             0,                 // Not used
                             aMouseInfo,        // Mouse information
                             SPIF_SENDCHANGE);  // Update Win.ini
    }  
}

Note

The winuser.h header defines SystemParametersInfo as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

See also

ACCESSTIMEOUT

ANIMATIONINFO

AUDIODESCRIPTION

FILTERKEYS

HIGHCONTRAST

ICONMETRICS

LOGFONT

MAKELANGID

MINIMIZEDMETRICS

MOUSEKEYS

NONCLIENTMETRICS

RECT

SERIALKEYS

SOUNDSENTRY

STICKYKEYS

SystemParametersInfoForDPI

TOGGLEKEYS

WM_SETTINGCHANGE

Windows Data Types