Window
Edit on GitHub| S | Return | Name | Parameters |
|---|---|---|---|
| Window | (uintptr handle = 0) | ||
| bool | IsValid | (void) const | |
| void | Close | (void) | |
| bool | IsTopMost | (void) const | |
| bool | IsBorderless | (void) const | |
| bool | IsMinimized | (void) const | |
| bool | IsMaximized | (void) const | |
| void | SetTopMost | (bool state) | |
| void | SetBorderless | (bool state) | |
| void | SetMinimized | (bool state) | |
| void | SetMaximized | (bool state) | |
| Process | GetProcess | (void) const | |
| int32 | GetPID | (void) const | |
| uintptr | GetHandle | (void) const | |
| bool | SetHandle | (uintptr handle) | |
| uintptr | GetHandleAx | (void) const | |
| string | GetTitle | (void) const | |
| void | SetTitle | (const char* title) | |
| Bounds | GetBounds | (void) const | |
| void | SetBounds | (const Bounds& b) | |
| void | SetBounds | (int32 x, int32 y, int32 w, int32 h) | |
| Bounds | GetClient | (void) const | |
| void | SetClient | (const Bounds& b) | |
| void | SetClient | (int32 x, int32 y, int32 w, int32 h) | |
| Point | MapToClient | (const Point& point) const | |
| Point | MapToScreen | (const Point& point) const | |
| Bounds | MapToClient | (const Bounds& bounds) const | |
| Bounds | MapToScreen | (const Bounds& bounds) const | |
| ✔ | WindowList | GetList | (const char* title = nullptr) |
| ✔ | Window | GetActive | (void) |
| ✔ | void | SetActive | (const Window& window) |
| ✔ | bool | IsAxEnabled | (bool options = false) |
| bool | operator == | (const Window& window) const | |
| bool | operator != | (const Window& window) const | |
| bool | operator == | (uintptr handle) const | |
| bool | operator != | (uintptr handle) const |
Description
Represents a single window in the underlying windowing system. A window is most commonly identified by a pointer to a handle, but because the class only attaches to existing windows, it never has to manage its own handles. To select a window, simply pass the handle of the target window to the Constructor or SetHandle function. In cases where the handle of the target window is not known, a list of all windows can be retrieved through the GetList function. To select the current active window, use the GetActive function. To check whether a window is still valid, use the IsValid function. Call SetHandle with zero to deselect the window and free up any used resources, although this is done by the destructor automatically, where needed.
After a window has been selected, the Window class offers several functions for manipulating the window in various ways. For instance, to manipulate the window title, use the GetTitle and SetTitle functions, to close the window, use the Close function. In addition to the built-in functions, the Window class also provides low-level access to the platform-dependent window handle, which can be used in conjunction with system calls to create custom functionality. This handle can be retrieved through the GetHandle and GetHandleAx functions.
The size of the window can be manipulated in two ways. The first is manipulating the window bounds and the second is manipulating the window client. Depending on the underlying windowing system, a window can be made up of two components, the border and the client. The border represents the platform-specific window decoration which hosts the icon, title and control buttons while the client represents the client area which hosts the application-specific content. To manipulate the total size of the window including the border and client, use the GetBounds and SetBounds functions. To manipulate the size of just the client, use the GetClient and SetClient functions. Manipulating the client may result in a larger window due to the border taking up space.
The Window class is also capable of converting client-area coordinates to screen-area coordinates, and vice versa. For example, the MapToClient function will convert the specified point in screen-area to client-area while the MapToScreen function will do the opposite. Variant functions accepting Bounds will perform the same operation, without modifying the width and height.
The Window class can also be used to set the current active window (i.e. the window accepting user input) by using the SetActive function. And on Mac, the IsAxEnabled can be used to check whether or not accessibility is enabled for the calling application. A return value of false will prevent most of the functions in the class from working. Comparison is supported as well.
Types
typedef vector<Window> Robot::WindowList;
Constructors
| Window | (uintptr handle = 0) |
Constructs a window with a call to SetHandle.
Functions
| bool | IsValid | (void) const |
Returns true if a window has been selected and is still currently accessible.
| void | Close | (void) |
Attempts to close the selected window. This function may not always cause the window to close, such as in the case of save prompts. On Mac, this function simulates a click on the close button, which may not necessarily terminate the application. In cases where the application needs to be terminated, consider killing it through GetProcess. Does nothing if no window is selected.
| bool | IsTopMost | (void) const |
| void | SetTopMost | (bool state) |
Gets or sets a value indicating whether the selected window appears in the topmost z-order. A topmost window appears above all other windows whose topmost property is false. A group of topmost windows will follow the same ordering as non-topmost windows (i.e. the current active window will be topmost). Returns false or does nothing if no window is selected.
Mac: This function is not available and will always return false.
Warning: It has been observed that some windows are unable to maintain their topmost status when appearing in front of fullscreen applications due to limitations in the underlying windowing system.
| bool | IsBorderless | (void) const |
| void | SetBorderless | (bool state) |
Gets or sets a value indicating whether the selected window is borderless. A borderless window hides the native window border and only displays the application-specific client content. Returns false or does nothing if no window is selected.
Mac: This function is not available and will always return false.
Warning: Not all windows and windowing systems are able to support border manipulation, and those that do may experience unexpected side effects. This function should be tested on a window by window basis.
| bool | IsMinimized | (void) const |
| bool | IsMaximized | (void) const |
| void | SetMinimized | (bool state) |
| void | SetMaximized | (bool state) |
Gets or sets a value indicating whether the selected window is restored, minimized, or maximized. A window can appear minimized, maximized, or both but it depends on the underlying windowing system to know what that means. Most often, a minimized window will appear hidden until the associated icon in the system taskbar is pressed, restoring the window to its former state. A maximized window will most often consume the entire screen space until it's restored, usually by using one of the window control buttons. On Mac, this function simulates a click on the minimize button. Returns false or does nothing if no window is selected.
Mac: Maximizing is not available and will always return false.
| Process | GetProcess | (void) const |
Returns a Process using GetPID.
| int32 | GetPID | (void) const |
Returns the identifier of the process that created the selected window. Returns zero if no window is selected.
| uintptr | GetHandle | (void) const |
Returns the platform-dependent handle to the selected window. If no window is selected, this function returns zero. On Linux, this function returns an X11 Window. On Mac, this function returns a Quartz CGWindowID. On Windows, this function returns a window HWND.
| bool | SetHandle | (uintptr handle) |
Attempts to select the window identified by handle, a platform-dependent handle to a window. On Linux, this function expects an X11 window. On Mac, this function expects a Quartz CGWindowID. On Windows, this function expects a window HWND. In all cases, these handles are managed by other applications and require no special handling. If a window has already been selected, it is deselected prior to selecting the new one, regardless of whether or not this function succeeded. If handle is zero, this function deselects any currently selected window and returns true. If handle is not zero and cannot be matched to a window, this function marks this class as invalid and returns false.
Mac: Due to limitations in the OSX API, this function may have performance implications. If selecting multiple windows, consider using GetList instead. This is because most of the functionality in this class depends on the Accessibility API, which requires an AXUIElementRef. Accessibility handles such as this one are managed resources, and therefore cannot be used to uniquely identify windows. To identify windows, a Quartz CGWindowID must be used instead, and since there is no way to easily convert them into AXUIElementRefs, all the windows in the associated process will need to be searched for one by one, until the right one is found.
Warning: Selecting 64-bit windows from 32-bit applications may yield incorrect results.
| uintptr | GetHandleAx | (void) const |
On Mac, returns an AXUIElementRef handle to the selected window. This handle is an allocated resource managed by this class and should not be manually deallocated. If no window is selected, this function returns zero. On Linux and Windows, this function will always return zero.
| string | GetTitle | (void) const |
| void | SetTitle | (const char* title) |
Gets or sets the title of the selected window, as a UTF-8 encoded string. The title is typically displayed at the top of the window, usually representing the name or state of the application. Returns an empty string or does nothing if no window is selected.
Warning: Not all windowing systems support spontaneous title modification, some don't even represent titles consistently across multiple windows, like in the case of Quartz Compositor on OSX. As such, this may result in unexpected side effects. This function should be tested on a window by window basis.
| Bounds | GetBounds | (void) const |
| void | SetBounds | (const Bounds& b) |
| void | SetBounds | (int32 x, int32 y, int32 w, int32 h) |
Gets or sets the total geometry of the selected window, in pixels, including the window border and client. The resulting Bounds is guaranteed to be normalized with X and Y represented in global screen coordinates, as is expected from bounds. If no window is selected, this function returns a Bounds with all components set to zero.
| Bounds | GetClient | (void) const |
| void | SetClient | (const Bounds& b) |
| void | SetClient | (int32 x, int32 y, int32 w, int32 h) |
Gets or sets the client geometry of the selected window, in pixels. This does not include the window border but rather just the application-specific content. To manipulate the total geometry, including the window border and client, use the GetBounds or SetBounds functions. The resulting Bounds is guaranteed to be normalized with X and Y represented in global screen coordinates, as is expected from bounds. If no window is selected, this function returns a Bounds with all components set to zero.
Warning: Not all windowing systems differentiate the border and client, some treat it as just one window, as in the case with Quartz Compositor on OSX. When that happens, these functions will be identical to GetBounds and SetBounds.
Note: Manipulating the client may result in a larger window due to the border taking up space.
| Point | MapToClient | (const Point& point) const |
| Point | MapToScreen | (const Point& point) const |
| Bounds | MapToClient | (const Bounds& bounds) const |
| Bounds | MapToScreen | (const Bounds& bounds) const |
Converts client-area coordinates to screen-area coordinates, and vice versa. Conversions are made using the client position of the selected window. If no window is selected, this function will return an object with all components set to zero. Functions accepting Bounds will perform the same operation, without modifying the width and height.
| static | WindowList | GetList | (const char* title = nullptr) |
Returns a list of all visible windows on the system. title accepts any valid case-insensitive ECMAScript regular expression which will be used to filter out windows by title. An empty list will be returned if the regular expression syntax is incorrect, as determined by regex.
| static | Window | GetActive | (void) |
| static | void | SetActive | (const Window& window) |
Gets or sets the current active window on the system. An active window is the user's current foreground window which is currently accepting user input. An active window will also be the top-most of all top-level windows that don't explicitly set the topmost property. If an error has occurred, GetActive returns an invalid window and SetActive does nothing. If no windows are active or no windows are open, the desktop element will be used.
Windows: GetActive may block in 20ms intervals up to a maximum of 20 times (400ms total) as it attempts to retrieve the active window. A block typically occurs when a new window is in the process of being activated but is not quite finished yet. Since these occurrences are so rare, this function will usually run without any blocks.
Warning: Not all windowing systems support active window manipulation.
| static | bool | IsAxEnabled | (bool options = false) |
On Mac, returns whether or not accessibility is enabled for the calling application. A return value of false will prevent most of the functions in this class from working. If options is true and the OSX version is greater than 10.9 (Mavericks), the user will be informed if the calling application is untrusted. This could be used, for example, on application startup to always warn a user if accessibility is not enabled. Prompting occurs asynchronously but requires the calling application to have a user interface (i.e. console applications won't display a prompt), however, the return value is unaffected. On Linux and Windows, this function will always return true.
Operators
| bool | operator == | (const Window& window) const |
| bool | operator != | (const Window& window) const |
| bool | operator == | (uintptr handle) const |
| bool | operator != | (uintptr handle) const |
Performs equality comparison to determine whether two windows have identical handles.
Examples
// C++
#include <Robot.h>
ROBOT_NS_USE_ALL;
int main (void)
{
// Must be true for the class to work
if (!Window::IsAxEnabled()) return 0;
// Retrieve the current active window
Window window = Window::GetActive();
window.IsValid (); // True if valid
window.IsMinimized(); // True if minimized
window.IsMaximized(); // True if maximized
window.GetTitle (); // Title of window
window.GetBounds (); // Window geometry
window.GetClient (); // Client geometry
// Reposition and resize the window
window.SetBounds (100, 200, 300, 400);
window.MapToClient (Point (0, 0)); // ~(-100, -200)
window.MapToScreen (Point (0, 0)); // ~( 100, 200)
// Gets process associated with window
Process process = window.GetProcess();
// List all other visible windows belonging
// to the same process as the active window
process.GetWindows();
// Create shared copy
Window copy = window;
copy.SetHandle (5); // True if valid and selectable
copy == window; // True because of shared ptr
copy != window; // False because of shared ptr
window.Close ( ); // Close the selected window
window.IsValid ( ); // False if window has closed
// Try debuggex.com for regex visualization
auto list = Window::GetList (".*title.*");
// List is an STL vector
for (const auto& w : list)
w.GetTitle(); // Always contains "title"
if (!list.empty())
// Activate the first match
Window::SetActive (list[0]);
return 0;
}
// Node
var robot = require ("robot-js");
// Must be true in order to work
if (robot.Window.isAxEnabled())
{
// Retrieve the current active window
var window = robot.Window.getActive();
window.isValid (); // True if valid
window.isMinimized(); // True if minimized
window.isMaximized(); // True if maximized
window.getTitle (); // Title of window
window.getBounds (); // Window geometry
window.getClient (); // Client geometry
// Reposition and resize the window
window.setBounds (100, 200, 300, 400);
window.mapToClient (0, 0); // ~(-100, -200)
window.mapToScreen (0, 0); // ~( 100, 200)
// Process associated with window
var process = window.getProcess();
// List all other visible windows belonging
// to the same process as the active window
process.getWindows();
// Create independent copy
var copy = window.clone();
copy.setHandle (5); // True if valid and selectable
copy.eq (window); // False because of new copy
copy.ne (window); // True because of new copy
window.close ( ); // Close the selected window
window.isValid ( ); // False if window has closed
// Try debuggex.com for regex visualization
var list = robot.Window.getList (".*title.*");
// List is an array
list.map (function (w)
{
w.getTitle(); // Always contains "title"
});
if (list.length > 0)
// Activate first window in list
robot.Window.setActive (list[0]);
}