#cp.ui.Window

A Window UI element.

#API Overview

Functions - API calls offered directly by the extension

findSectionUI
matches

Constructors - API calls which return an object, typically one that offers API methods

Window

Fields - Variables which can only be accessed from an object returned by a constructor

alert
exists
focused
frame
hsWindow
id
isFullScreen
isShowing
minimized
position
size
UI
visible

Methods - API calls which can only be made on an object returned by a constructor

close
doClose
doFocus
findSectionUI
focus
notifier
snapshot

#API Documentation

#Functions

#findSectionUI


Signature	`cp.ui.Window.findSectionUI(windowUI, sectionID) -> hs.axuielement`
Type	Function
Description	Finds the `axuielement` for the specified `sectionID`, if present in the provided `axuielement` `windowUI`.
Parameters	windowUI - The `AXWindow` `axuielement` to search in. sectionID - The string value for the `SectionUniqueID`.
Returns	The matching `axuielement`, or `nil`.
Notes	None
Examples	None
Source	src/extensions/cp/ui/Window.lua line 381

#matches


Signature	`cp.ui.Window.matches(element) -> boolean`
Type	Function
Description	Checks if the provided element is a valid window.
Parameters	element - An element to check
Returns	A boolean
Notes	None
Examples	None
Source	src/extensions/cp/ui/Window.lua line 24

#Constructors

#Window


Signature	`cp.ui.Window(cpApp, uiProp) -> Window`
Type	Constructor
Description	Creates a new Window
Parameters	`cpApp` - a `cp.app` for the application the Window belongs to. `uiProp` - a `cp.prop` that returns the `hs.axuielement` for the window.
Returns	A new `Window` instance.
Notes	None
Examples	None
Source	src/extensions/cp/ui/Window.lua line 48

#Fields

#alert


Signature	`cp.ui.Window.alert <cp.ui.Alert>`
Type	Field
Description	Provides access to any 'Alert' windows on the Window.
Notes	None
Source	src/extensions/cp/ui/Window.lua line 374

#exists


Signature	`cp.ui.Window.exists <cp.prop: boolean; read-only>`
Type	Field
Description	Returns `true` if the window exists. It may not be visible.
Notes	None
Source	src/extensions/cp/ui/Window.lua line 174

#focused


Signature	`cp.ui.Window.focused <cp.prop: boolean>`
Type	Field
Description	Is `true` if the window has mouse/keyboard focused.
Notes	None
Source	src/extensions/cp/ui/Window.lua line 132

#frame


Signature	`cp.ui.Window.frame <cp.prop: hs.geometry rect>`
Type	Field
Description	The `hs.geometry` rect value describing the window's position.
Notes	None
Source	src/extensions/cp/ui/Window.lua line 206

#hsWindow


Signature	`cp.ui.Window.hsWindow <cp.prop: hs.window; read-only>`
Type	Field
Description	The `hs.window` instance for the window, or `nil` if it can't be found.
Notes	None
Source	src/extensions/cp/ui/Window.lua line 78

#id


Signature	`cp.ui.Window.id <cp.prop: string; read-only>`
Type	Field
Description	The window title, or `nil` if the window is not currently visible.
Notes	None
Source	src/extensions/cp/ui/Window.lua line 105

#isFullScreen


Signature	`cp.ui.Window.isFullScreen <cp.prop: boolean>`
Type	Field
Description	Returns `true` if the window is full-screen.
Notes	None
Source	src/extensions/cp/ui/Window.lua line 273

#isShowing


Signature	`cp.ui.Window.isShowing <cp.prop: boolean; read-only; live?>`
Type	Field
Description	Indicates if the `Window` is currently showing on screen.
Notes	None
Source	src/extensions/cp/ui/Window.lua line 71

#minimized


Signature	`cp.ui.Window.minimized <cp.prop: boolean>`
Type	Field
Description	Returns `true` if the window exists and is minimised.
Notes	None
Source	src/extensions/cp/ui/Window.lua line 181

#position


Signature	`cp.ui.Window.position <cp.prop: table>`
Type	Field
Description	Gets or sets the window position
Notes	None
Source	src/extensions/cp/ui/Window.lua line 251

#size


Signature	`cp.ui.Window.size <cp.prop: table>`
Type	Field
Description	Gets or sets the window size
Notes	None
Source	src/extensions/cp/ui/Window.lua line 229

#UI


Signature	`cp.ui.Window.UI <cp.prop: hs.axuielement: read-only; live?>`
Type	Field
Description	The UI `axuielement` for the Window.
Notes	None
Source	src/extensions/cp/ui/Window.lua line 63

#visible


Signature	`cp.ui.Window.visible <cp.prop: boolean; read-only>`
Type	Field
Description	Returns `true` if the window is visible on a screen.
Notes	None
Source	src/extensions/cp/ui/Window.lua line 117

#Methods

#close


Signature	`cp.ui.Window:close() -> boolean`
Type	Method
Description	Attempts to close the window.
Parameters	None
Returns	`true` if the window was successfully closed.
Notes	None
Examples	None
Source	src/extensions/cp/ui/Window.lua line 299

#doClose


Signature	`cp.ui.Window:doClose() -> cp.rx.go.Statement <boolean>`
Type	Method
Description	Returns a Statement that will attempt to close the window, if it is visible.
Parameters	None
Returns	The `Statement` to execute, resolving to `true` if the window is closed successfully, or `false` if not.
Notes	None
Examples	None
Source	src/extensions/cp/ui/Window.lua line 313

#doFocus


Signature	`cp.ui.Window:doFocus() -> cp.rx.go.Statement`
Type	Method
Description	Returns a Statement will attempt to focus on the window, if it is visible.
Parameters	None
Returns	The `Statement` to execute, which resolves to `true` if the window was successfully focused, or `false` if not.
Notes	None
Examples	None
Source	src/extensions/cp/ui/Window.lua line 345

#findSectionUI


Signature	`cp.ui.Window:findSectionUI(sectionID) -> hs.axuielement`
Type	Method
Description	Looks for th section with the specified `SectionUniqueID` value and returns the matching `axuielement` value.
Parameters	sectionID - The string for the section ID.
Returns	The matching `axuielement`, or `nil`.
Notes	None
Examples	None
Source	src/extensions/cp/ui/Window.lua line 404

#focus


Signature	`cp.ui.Window:focus() -> boolean`
Type	Method
Description	Attempts to focus the window.
Parameters	None
Returns	`true` if the window was successfully focused.
Notes	None
Examples	None
Source	src/extensions/cp/ui/Window.lua line 331

#notifier


Signature	`cp.ui.Window:notifier() -> cp.ui.notifier`
Type	Method
Description	Returns a `notifier` that is tracking the application UI element. It has already been started.
Parameters	None
Returns	The notifier.
Notes	None
Examples	None
Source	src/extensions/cp/ui/Window.lua line 417

#snapshot


Signature	`cp.ui.Window:snapshot([path]) -> hs.image \| nil`
Type	Method
Description	Takes a snapshot of the UI in its current state as a PNG and returns it. If the `path` is provided, the image will be saved at the specified location.
Parameters	path - (optional) The path to save the file. Should include the extension (should be `.png`).
Returns	The `hs.image` that was created, or `nil` if the UI is not available.
Notes	None
Examples	None
Source	src/extensions/cp/ui/Window.lua line 430