System Metrics (Win32 UI)

This document provides a comprehensive reference to the system metric values that can be retrieved using the GetSystemMetrics function in the Windows API. These metrics provide information about the state and characteristics of the Windows environment, such as screen dimensions, input device status, and UI element sizes.

Introduction

The GetSystemMetrics function is a powerful tool for developers to query information about the user's desktop environment. This information can be used to adapt applications to different screen resolutions, input devices, and user preferences, ensuring a consistent and optimal user experience.

Function Signature


int GetSystemMetrics(
  [in] int nIndex
);

Parameters

System Metric Flags

The following table lists the most common system metric flags and their corresponding return values:

Flag Description Return Value
SM_CXSCREEN The width of the screen's virtual screen, in pixels. The virtual screen is the largest possible screen area that contains all displays. Pixels
SM_CYSCREEN The height of the screen's virtual screen, in pixels. Pixels
SM_CXFIXEDFRAME The width of a window border, in pixels. This is the width of the vertical border of a window that has a sizable border. Pixels
SM_CYFIXEDFRAME The height of a window border, in pixels. This is the height of the horizontal border of a window that has a sizable border. Pixels
SM_CXDLGFRAME The width of the dialog-window frame, in pixels. This is the width of the border around a dialog box that does not include a title bar. Pixels
SM_CYDLGFRAME The height of the dialog-window frame, in pixels. This is the height of the border around a dialog box that does not include a title bar. Pixels
SM_CXSMCAPTION The width of a small caption button, in pixels. Pixels
SM_CYSMCAPTION The height of a small caption button, in pixels. Pixels
SM_CXMENU The width of the menu bar, in pixels. Pixels
SM_CYMENU The height of the menu bar, in pixels. Pixels
SM_CXFULLSCREEN The width of the client area of a full-screen window, in pixels. Pixels
SM_CYFULLSCREEN The height of the client area of a full-screen window, in pixels. Pixels
SM_CYKANJI The height of a Kanji window, in pixels. Pixels
SM_CUOTHER The number of other system metric values, in the range 0-31, that are valid. Count
SM_CXDRAG The thickness of the drag rectangle used for moving windows, in pixels. Pixels
SM_CYDRAG The height of the drag rectangle used for moving windows, in pixels. Pixels
SM_SHOWSOUNDS Nonzero if the current user has chosen to display "\uFFfd" in the System tray. Boolean (0 or 1)
SM_CXICON The width and height of a default icon, in pixels. Users can sign-in to change the dimensions of their icons. Pixels
SM_CYICON The width and height of a default icon, in pixels. Users can sign-in to change the dimensions of their icons. Pixels
SM_CXCURSOR The width of a cursor, in pixels. Pixels
SM_CYCURSOR The height of a cursor, in pixels. Pixels
SM_CXMAXIMIZED The width of a window, in pixels, when it is maximized. Pixels
SM_CYMAXIMIZED The height of a window, in pixels, when it is maximized. Pixels
SM_NETWORK The least significant bit of the return value is set if there is at least one vertex in the user's network. Boolean (0 or 1)
SM_CLEANBOOT The computer is starting with the CleanBoot option. Boolean (0 or 1)
SM_CXEDGE The width of the 3-D border, in pixels. Pixels
SM_CYEDGE The height of the 3-D border, in pixels. Pixels
SM_CXMINORVERSPACING The horizontal distance between window metric displays, in pixels. Pixels
SM_CYMINORVERSPACING The vertical distance between window metric displays, in pixels. Pixels
SM_CXDOUBLECLICK The width of the rectangle used to detect double-clicks, in pixels. Pixels
SM_CYDOUBLECLICK The height of the rectangle used to detect double-clicks, in pixels. Pixels
SM_CXICONSPACING The recommended width of icons, in pixels. Pixels
SM_CYICONSPACING The recommended height of icons, in pixels. Pixels
SM_SWAPBUTTON Nonzero if the user has swapped the left and right mouse buttons. Boolean (0 or 1)
SM_CXMINIMIZED The width of a minimized window, in pixels. Pixels
SM_CYMINIMIZED The height of a minimized window, in pixels. Pixels
SM_CMONITORS The number of display monitors on the desktop. Returns 0 if there is only one monitor. Count
SM_MAXIMUMTOUCHES The maximum number of concurrent touch indicators that the system can support. Count
SM_PENWINDOWS Nonzero if the system is Windows for Pen computing. Boolean (0 or 1)
SM_DBCSENABLED Nonzero if the system is operating in Arabic or Hebrew mode. Boolean (0 or 1)
SM_CMETRICS The number of system metric values, in the range 0-31, that are valid. Count
SM_SAMEDISPLAY Nonzero if all the display monitors are the same size. Boolean (0 or 1)
SM_RESERVED1 Reserved. N/A
SM_RESERVED2 Reserved. N/A
SM_RESERVED3 Reserved. N/A
SM_RESERVED4 Reserved. N/A
SM_CXICONSM The width of a small icon, in pixels. Pixels
SM_CYICONSM The height of a small icon, in pixels. Pixels
SM_CXCHANNELS The width of the vertical scroll bar, in pixels. Pixels
SM_CYCHANNELS The height of the horizontal scroll bar, in pixels. Pixels
SM_GRAPHICS Nonzero if the system is a graphics device interface (GDI) device. Boolean (0 or 1)
SM_DEBUG Nonzero if the system is a debugging version. Boolean (0 or 1)
SM_MENUDROPALIGNMENT Nonzero if menus are aligned for double-byte character sets. Boolean (0 or 1)
SM_CANNAMECHANGE Nonzero if the system can change the name of a device. Boolean (0 or 1)
SM_SETREDraw Nonzero if the system has changed the user's color and metrics. Boolean (0 or 1)
SM_MOUSEPRESENT Nonzero if a mouse is present. Boolean (0 or 1)
SM_XVIRTUALSCREEN The coordinates of the left side of the virtual screen. Pixels
SM_YVIRTUALSCREEN The coordinates of the top side of the virtual screen. Pixels
SM_CXVIRTUALSCREEN The width of the virtual screen, in pixels. Pixels
SM_CYVIRTUALSCREEN The height of the virtual screen, in pixels. Pixels
SM_CMETRICS_NEW The number of metrics that are defined in this header file. Count
SM_CMETRICS_RESERVED The number of metrics that are currently reserved. Count
SM_CMETRICS_OLD The number of metrics that are defined in the earlier version of this header file. Count

Example Usage

The following C++ code snippet demonstrates how to retrieve and display the screen width and height:


#include <windows.h>
#include <iostream>

int main() {
    int screenWidth = GetSystemMetrics(SM_CXSCREEN);
    int screenHeight = GetSystemMetrics(SM_CYSCREEN);

    std::cout << "Screen Width: " << screenWidth << " pixels" << std::endl;
    std::cout << "Screen Height: " << screenHeight << " pixels" << std::endl;

    if (GetSystemMetrics(SM_SWAPBUTTON)) {
        std::cout << "Mouse buttons are swapped." << std::endl;
    } else {
        std::cout << "Mouse buttons are not swapped." << std::endl;
    }

    return 0;
}

Note:

The values returned by GetSystemMetrics can vary based on the user's display settings, hardware configuration, and Windows theme. Always test your application on different configurations to ensure compatibility.

Warning:

Some system metrics might change dynamically, especially when the user logs in or out, or when display settings are altered. Applications should not cache these values indefinitely and should be prepared to re-query them if necessary.

Related Topics