Screen

#include <Screen.h>

S	Return	Name	Parameters
		Screen	(void)
		Screen	(const Bounds& bounds, const Bounds& usable)

	Bounds	GetBounds	(void) const
	Bounds	GetUsable	(void) const
	bool	IsPortrait	(void) const
	bool	IsLandscape	(void) const
✔	bool	Synchronize	(void)
✔	Screen*	GetMain	(void)
✔	ScreenList	GetList	(void)
✔	Screen*	GetScreen	(const Window& window)
✔	Screen*	GetScreen	(const Point & point )
✔	Screen*	GetScreen	(int32 px, int32 py)
✔	bool	GrabScreen	(Image& image, const Bounds& bounds, const Window& window = Window())
✔	bool	GrabScreen	(Image& image, int32 x = 0, int32 y = 0, int32 w = 0, int32 h = 0, const Window& window = Window())
✔	Bounds	GetTotalBounds	(void)
✔	Bounds	GetTotalUsable	(void)
✔	bool	IsCompositing	(void)
✔	void	SetCompositing	(bool enabled)

Description

Represents a single screen available on the system. A screen is any physical or virtual display device or monitor attached to the computer. Before using most functions in the class, a call to Synchronize must be made. This function will gather the most up to date information about the display devices attached to the system and then caches it. This function must return true for most of the functionality in the class to work.

After synchronization, the Screen class offers several functions for retrieving useful information about the display devices attached to the system. For instance, to retrieve a list of all available screens, use the GetList function. To retrieve the primary/default screen, use the GetMain function. To retrieve the screen at a position, use any of the GetScreen functions.

After a screen has been retrieved, use the accessor functions to extract a variety of useful information. For example, to retrieve the geometry of a screen, use the GetBounds function. To retrieve just the usable geometry of a screen, use the GetUsable function. To determine whether a screen is portrait or landscape, use the IsPortrait or IsLandscape function. The total geometry across all screens can be retrieved through the GetTotalBounds function. Similarly, the total usable geometry across all screens can be retrieved through the GetTotalUsable function.

The Screen class also offers the ability to take screenshots of entire screens or portions of screens using the GrabScreen function. And on Windows 7 and below, Aero can be toggled on and off using the IsCompositing and SetCompositing functions.

Types

typedef deque<Screen*> Robot::ScreenList;

Constructors

    
        


            Screen
            (void)
        
        


            Screen
            (const Bounds& bounds,
 const Bounds& usable)

Constructs a local screen with all components set to the parameters.

Functions

    
        

            Bounds
            GetBounds
            (void) const

Returns the geometry of the screen in pixels. As an example this might return (0, 0, 1920, 1080), or (1920, 0, 1920, 1080) if operating in a virtual desktop environment.

    
        

            Bounds
            GetUsable
            (void) const

Returns the usable geometry of the screen in pixels. The usable geometry excludes window manager reserved areas such as task bars, system menus and gutter.

    
        

            bool
            IsPortrait
            (void) const
        
        

            bool
            IsLandscape
            (void) const

Returns true depending on whether the screen or portrait or landscape.

    
        
            static
            bool
            Synchronize
            (void)

Gathers the most up to date information about display devices attached to the system and caches the results. This function must be called before calling any other function in this class, unless otherwise specified. If this function is not called or it fails by returning false, other functions in this class will return invalid or otherwise incorrect data. This function can be called multiple times throughout the lifetime of an application, but beware as calling it too many times within a short period can have performance implications.

    
        
            static
            Screen*
            GetMain
            (void)

Returns the primary/default screen on the system, or null if there is none.

    
        
            static
            ScreenList
            GetList
            (void)

Returns a list of all screens available to the application on the system.

    
        
            static
            Screen*
            GetScreen
            (const Window& window)
        
        
            static
            Screen*
            GetScreen
            (const Point & point )
        
        
            static
            Screen*
            GetScreen
            (int32  px, int32  py)

Returns the screen at point. This function will return the main screen if the point is out of bounds or null if there are no available screens. When passing a window, the point at the center of the window bounds will be used in place of point, however, if window is invalid, this function will return null.

    
        
            static
            bool
            GrabScreen
            (Image& image, const Bounds& bounds,
 const Window& window = Window())
        
        
            static
            bool
            GrabScreen
            (Image& image,
 int32 x = 0, int32 y = 0,
 int32 w = 0, int32 h = 0,
 const Window& window = Window())

Takes a screenshot of the system or window, minus the mouse cursor, at bounds and then copies the result into image. When specifying a window, the accuracy of the resulting image depends greatly on the underlying platform. For instance, windows which are partially off-screen or are otherwise obscured by other windows may have parts of it cut off, so be sure to test for all conditions when using this function. When an error occurs this function will return false. Moreover, image will only be overwritten when data is about to be copied into it, therefore a return value of false will never cause image to be modified.

When width or height is zero or negative, their values are individually set to window client. If window is invalid, the values are instead individually set to the total bounds of the system. It is important to ensure that bounds do not fall outside the boundaries of the screen or window, doing so will result in a variety of platform-dependent errors. While some of these errors may only cause the out of bounds regions to become black or contain invalid data, some platforms will out right cause this function to fail.

The performance of this function ranges dramatically from platform to platform. Even certain conditions and system configurations can cause the performance of this function to fluctuate. Therefore it is strongly advised to perform benchmarks to determine the viability of this function. Sometimes, certain tweaks such as disabling Aero on Windows can be made to improve performance but overall, applications needing real-time solutions may need to rely on alternative methods to capture the screen.

Note: This function does not require synchronization when specifying a width and height.

    
        
            static
            Bounds
            GetTotalBounds
            (void)

Returns the total geometry across all screens in pixels. This value is determined by combining the bounds of all screens on the system during class synchronization.

    
        
            static
            Bounds
            GetTotalUsable
            (void)

Returns the total usable geometry across all screens in pixels. The usable geometry excludes window manager reserved areas such as task bars, system menus and gutter. This value is determined by combining the usable bounds of all screens on the system during class synchronization.

    
        
            static
            bool
            IsCompositing
            (void)
        
        
            static
            void
            SetCompositing
            (bool enabled)

On Windows 7 and below, gets or sets the current enabled state of Windows Aero. If enabled is false, the transparent glass effect, among other features, will be disabled. Certain applications, particularly those with high interactivity, will gain dramatic performance increases with Aero disabled. Additionally, the performance of GrabScreen may also improve with Aero disabled, however, capturing individual windows hidden behind other windows will no longer work. Windows Aero will be automatically enabled when the application terminates. On Linux, Mac and Windows 8 and above, this function does nothing and will always return true.

Note: This function does not require synchronization.

Examples

// C++
#include <Robot.h>
ROBOT_NS_USE_ALL;

int main (void)
{
    // Must be true for the class to work
    if (!Screen::Synchronize()) return 0;

    // Total / usable bounds
    Screen::GetTotalBounds();
    Screen::GetTotalUsable();

    // Retrieve the primary screen
    auto main = Screen::GetMain();

    // Retrieve list of all screens
    auto list = Screen::GetList();

    // List is an STL vector
    for (const auto* s : list)
    {
        s->GetBounds(); // Total  bounds
        s->GetUsable(); // Usable bounds
    }

    // Disable Windows compositing
    // (also known as Windows Aero)
    Screen:: IsCompositing ();
    Screen::SetCompositing (false);

    Image output;
    // Take a screenshot of the
    // entire desktop and store
    // it in the output image
    Screen::GrabScreen (output);
    return 0;
}

// Node
var robot = require ("robot-js");

// Must be true in order to work
if (robot.Screen.synchronize())
{
    // Get total and usable bounds
    robot.Screen.getTotalBounds();
    robot.Screen.getTotalUsable();

    // Retrieve the primary screen
    var main = robot.Screen.getMain();

    // Retrieve list of all screens
    var list = robot.Screen.getList();

    // List is an array
    list.map (function (s)
    {
        s.getBounds(); // Total  bounds
        s.getUsable(); // Usable bounds
    });

    // Disable Windows compositing
    // (also known as Windows Aero)
    robot.Screen. isCompositing ();
    robot.Screen.setCompositing (false);

    var output = robot.Image();
    // Take a screenshot of the
    // entire desktop and store
    // it in the output image
    robot.Screen.grabScreen (output);
}

static	Screen*	GetScreen	(const Window& window)
static	Screen*	GetScreen	(const Point & point )
static	Screen*	GetScreen	(int32 px, int32 py)