Class OutputHandle
An output handle.
This is a handle to one of your monitors. It serves to make it easier to deal with them, defining methods for getting properties and helpers for things like positioning multiple monitors.
This can be retrieved through the various get
functions in the Output
module.
Fields
name
name
: string
The unique name of this output
Functions
method set_location
function OutputHandle:set_location(loc: { x: integer, y: integer })
Set the location of this output in the global space.
On startup, Pinnacle will lay out all connected outputs starting at (0, 0) and going to the right, with their top borders aligned.
This method allows you to move outputs where necessary.
Note: If you have space between two outputs when setting their locations, the pointer will not be able to move between them.
Example
-- Assume two monitors in order, "DP-1" and "HDMI-1", with the following dimensions:
-- - "DP-1": ┌─────┐
-- │ │1920x1080
-- └─────┘
-- - "HDMI-1": ┌───────┐
-- │ 2560x │
-- │ 1440 │
-- └───────┘
Output.get_by_name("DP-1"):set_location({ x = 0, y = 0 })
Output.get_by_name("HDMI-1"):set_location({ x = 1920, y = -360 })
-- Results in:
-- ┌───────┐
-- ┌─────┤ │
-- │DP-1 │HDMI-1 │
-- └─────┴───────┘
-- Notice that y = 0 aligns with the top of "DP-1", and the top of "HDMI-1" is at y = -360.
Parameters
loc
: { x: integer, y: integer }
See also
method set_loc_adj_to
function OutputHandle:set_loc_adj_to(other: OutputHandle, alignment: Alignment)
Set the location of this output adjacent to another one.
alignment
is how you want this output to be placed. For example, "top_align_left" will place this output above other
and align the left borders. Similarly, "right_align_center" will place this output to the right of other
and align their centers.
Example
-- Assume two monitors in order, "DP-1" and "HDMI-1", with the following dimensions:
-- - "DP-1": ┌─────┐
-- │ │1920x1080
-- └─────┘
-- - "HDMI-1": ┌───────┐
-- │ 2560x │
-- │ 1440 │
-- └───────┘
Output.get_by_name("DP-1"):set_loc_adj_to(Output:get_by_name("HDMI-1"), "bottom_align_right")
-- Results in:
-- ┌───────┐
-- │ │
-- │HDMI-1 │
-- └──┬────┤
-- │DP-1│
-- └────┘
-- Notice that "DP-1" now has the coordinates (2280, 1440) because "DP-1" is getting moved, not "HDMI-1".
-- "HDMI-1" was placed at (1920, 0) during the compositor's initial output layout.
Parameters
other
: OutputHandle
alignment
: Alignment
method set_mode
function OutputHandle:set_mode(pixel_width: integer, pixel_height: integer, refresh_rate_millihz?: integer)
Set this output's mode.
If refresh_rate_millihz
is provided, Pinnacle will attempt to use the mode with that refresh rate. If it isn't, Pinnacle will attempt to use the mode with the highest refresh rate that matches the given size.
The refresh rate is in millihertz. For example, to choose a mode with a refresh rate of 60Hz, use 60000.
If this output doesn't support the given mode, it will be ignored.
Example
Output.get_focused():set_mode(2560, 1440, 144000)
Parameters
pixel_width
: integer
pixel_height
: integer
refresh_rate_millihz?
: integer
method set_modeline
function OutputHandle:set_modeline(modeline: string | Modeline)
Set a custom modeline for this output.
This accepts a Modeline
table or a string of the modeline.
Parameters
modeline
: string | Modeline
method set_scale
function OutputHandle:set_scale(scale: number)
Set this output's scaling factor.
Parameters
scale
: number
method increase_scale
function OutputHandle:increase_scale(increase_by: number)
Increase this output's scaling factor.
Parameters
increase_by
: number
method decrease_scale
function OutputHandle:decrease_scale(decrease_by: number)
Decrease this output's scaling factor.
Parameters
decrease_by
: number
method set_transform
function OutputHandle:set_transform(transform: Transform)
Set this output's transform.
Parameters
transform
: Transform
method set_powered
function OutputHandle:set_powered(powered: boolean)
Power on or off this output.
Parameters
powered
: boolean
method props
function OutputHandle:props()
-> OutputProperties
Get all properties of this output.
Returns
method make
function OutputHandle:make()
-> string
Get this output's make.
Note: make and model detection are currently somewhat iffy and may not work.
Shorthand for handle:props().make
.
Returns
string
method model
function OutputHandle:model()
-> string
Get this output's model.
Note: make and model detection are currently somewhat iffy and may not work.
Shorthand for handle:props().model
.
Returns
string
method x
function OutputHandle:x()
-> integer
Get this output's x-coordinate in the global space.
Shorthand for handle:props().x
.
Returns
integer
method y
function OutputHandle:y()
-> integer
Get this output's y-coordinate in the global space.
Shorthand for handle:props().y
.
Returns
integer
method logical_width
function OutputHandle:logical_width()
-> integer
Get this output's logical width in pixels.
If the output is disabled, this returns nil.
Shorthand for handle:props().logical_width
.
Returns
integer
method logical_height
function OutputHandle:logical_height()
-> integer
Get this output's logical height in pixels.
If the output is disabled, this returns nil.
Shorthand for handle:props().y
.
Returns
integer
method current_mode
function OutputHandle:current_mode()
-> Mode
Get this output's current mode.
Shorthand for handle:props().current_mode
.
Returns
method preferred_mode
function OutputHandle:preferred_mode()
-> Mode
Get this output's preferred mode.
Shorthand for handle:props().preferred_mode
.
Returns
method modes
function OutputHandle:modes()
-> Mode[]
Get all of this output's available modes.
Shorthand for handle:props().modes
.
Returns
Mode[]
method physical_width
function OutputHandle:physical_width()
-> integer
Get this output's physical width in millimeters.
Shorthand for handle:props().physical_width
.
Returns
integer
method physical_height
function OutputHandle:physical_height()
-> integer
Get this output's physical height in millimeters.
Shorthand for handle:props().physical_height
.
Returns
integer
method focused
function OutputHandle:focused()
-> boolean
Get whether or not this output is focused.
The focused output is currently implemented as the one that last had pointer motion.
Shorthand for handle:props().focused
.
Returns
boolean
method tags
function OutputHandle:tags()
-> TagHandle[]
Get the tags this output has.
Shorthand for handle:props().tags
.
Returns
method scale
function OutputHandle:scale()
-> number
Get this output's scaling factor.
Shorthand for handle:props().scale
.
Returns
number
method transform
function OutputHandle:transform()
-> Transform
Get this output's transform.
Shorthand for handle:props().transform
.
Returns
method serial
function OutputHandle:serial()
-> string
Get this output's EDID serial.
Shorthand for handle:props().serial
.
Returns
string
method keyboard_focus_stack
function OutputHandle:keyboard_focus_stack()
-> WindowHandle[]
Get this output's keyboard focus stack.
This includes all windows on the output, even those on inactive tags. If you only want visible windows, use keyboard_focus_stack_visible
instead.
Shorthand for handle:props().keyboard_focus_stack
.
Returns
See also
method enabled
function OutputHandle:enabled()
-> boolean
Get whether this output is enabled.
Disabled outputs are not mapped to the global space and cannot be used.
Returns
boolean
method powered
function OutputHandle:powered()
-> boolean
Get whether this output is powered.
Unpowered outputs that are enabled will be off, but they will still be mapped to the global space, meaning you can still interact with them.
Returns
boolean
method keyboard_focus_stack_visible
function OutputHandle:keyboard_focus_stack_visible()
-> WindowHandle[]
Get this output's keyboard focus stack.
This only includes windows on active tags. If you want all windows on the output, use keyboard_focus_stack
instead.