Lua Reference

Appearance

Class pinnacle.output.OutputHandle ​

An output handle.

This is a handle to one of your 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_loc ​

function pinnacle.output.OutputHandle:set_loc(x: integer, y: integer)

Sets 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 ​

lua
 -- 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(0, 0)
Output.get_by_name("HDMI-1"):set_loc(1920, -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 ​

x: integer
y: integer

See also ​

method set_loc_adj_to ​

function pinnacle.output.OutputHandle:set_loc_adj_to(other: pinnacle.output.OutputHandle, alignment: pinnacle.output.Alignment)

Sets 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 ​

lua
 -- 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: pinnacle.output.OutputHandle
alignment: pinnacle.output.Alignment

method set_mode ​

function pinnacle.output.OutputHandle:set_mode(width: integer, height: integer, refresh_rate_mhz?: integer)

Sets this output's mode.

If refresh_rate_mhz 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 ​

lua
Output.get_focused():set_mode(2560, 1440, 144000)

Parameters ​

width: integer
height: integer
refresh_rate_mhz?: integer

method set_custom_mode ​

function pinnacle.output.OutputHandle:set_custom_mode(width: integer, height: integer, refresh_rate_mhz?: integer)

Sets this output's mode to a custom one.

If refresh_rate_mhz is provided, Pinnacle will create a new mode with that refresh rate. If it isn't, it will default to 60Hz.

The refresh rate is in millihertz. For example, to choose a mode with a refresh rate of 60Hz, use 60000.

Example ​

lua
Output.get_focused():set_custom_mode(2560, 1440, 75000)

Parameters ​

width: integer
height: integer
refresh_rate_mhz?: integer

method set_modeline ​

function pinnacle.output.OutputHandle:set_modeline(modeline: string | pinnacle.output.Modeline)

Sets a custom modeline for this output.

This accepts a Modeline table or a string of the modeline. You can parse a modeline into a Modeline table with

lua
require("pinnacle.util").output.parse_modeline("your modeline herre")

Parameters ​

modeline: string | pinnacle.output.Modeline

method set_scale ​

function pinnacle.output.OutputHandle:set_scale(scale: number)

Sets this output's scaling factor.

Parameters ​

scale: number

method change_scale ​

function pinnacle.output.OutputHandle:change_scale(change_by: number)

Changes this output's scaling factor by the given amount.

Parameters ​

change_by: number

method set_transform ​

function pinnacle.output.OutputHandle:set_transform(transform: pinnacle.output.Transform)

Sets this output's transform.

Parameters ​

transform: pinnacle.output.Transform

method set_powered ​

function pinnacle.output.OutputHandle:set_powered(powered: boolean)

Powers on or off this output.

Parameters ​

powered: boolean

method toggle_powered ​

function pinnacle.output.OutputHandle:toggle_powered()

Toggles power for this output.

method make ​

function pinnacle.output.OutputHandle:make()
    -> string

Gets this output's make.

Returns ​

  1. string

method model ​

function pinnacle.output.OutputHandle:model()
    -> string

Gets this output's model.

Returns ​

  1. string

method serial ​

function pinnacle.output.OutputHandle:serial()
    -> string

Gets this output's serial.

Returns ​

  1. string

method loc ​

function pinnacle.output.OutputHandle:loc()
    -> { x: integer, y: integer }

Gets this output's location in the global space.

Returns ​

  1. { x: integer, y: integer }

method logical_size ​

function pinnacle.output.OutputHandle:logical_size()
    -> { width: integer, height: integer }

Gets this output's logical size in logical pixels.

If the output is disabled, this returns nil.

Returns ​

  1. { width: integer, height: integer }

method physical_size ​

function pinnacle.output.OutputHandle:physical_size()
    -> { width: integer, height: integer }

Gets this output's physical size in millimeters.

Returns ​

  1. { width: integer, height: integer }

method current_mode ​

function pinnacle.output.OutputHandle:current_mode()
    -> pinnacle.output.Mode

Gets this output's current mode.

Returns ​

  1. pinnacle.output.Mode

method preferred_mode ​

function pinnacle.output.OutputHandle:preferred_mode()
    -> pinnacle.output.Mode

Gets this output's preferred mode.

Returns ​

  1. pinnacle.output.Mode

method modes ​

function pinnacle.output.OutputHandle:modes()
    -> pinnacle.output.Mode[]

Gets all of this output's available modes.

Returns ​

  1. pinnacle.output.Mode[]

method focused ​

function pinnacle.output.OutputHandle:focused()
    -> boolean

Gets whether or not this output is focused.

The focused output is currently implemented as the one that last had pointer motion.

Returns ​

  1. boolean

method tags ​

function pinnacle.output.OutputHandle:tags()
    -> pinnacle.tag.TagHandle[]

Gets the tags this output has.

Returns ​

  1. pinnacle.tag.TagHandle[]

method scale ​

function pinnacle.output.OutputHandle:scale()
    -> number

Get this output's scale.

Returns ​

  1. number

method transform ​

function pinnacle.output.OutputHandle:transform()
    -> pinnacle.output.Transform

Get this output's transform.

Returns ​

  1. pinnacle.output.Transform

method enabled ​

function pinnacle.output.OutputHandle:enabled()
    -> boolean

Gets whether this output is enabled.

Disabled outputs are not mapped to the global space and cannot be used.

Returns ​

  1. boolean

method powered ​

function pinnacle.output.OutputHandle:powered()
    -> boolean

Gets 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 ​

  1. boolean

method keyboard_focus_stack ​

function pinnacle.output.OutputHandle:keyboard_focus_stack()
    -> pinnacle.window.WindowHandle[]

Gets 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.

Returns ​

  1. pinnacle.window.WindowHandle[]

See also ​

method keyboard_focus_stack_visible ​

function pinnacle.output.OutputHandle:keyboard_focus_stack_visible()
    -> pinnacle.window.WindowHandle[]

Gets 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.

Returns ​

  1. pinnacle.window.WindowHandle[]

See also ​