Struct OutputHandle

pub struct OutputHandle { /* private fields */ }

A handle to an output.

This allows you to manipulate outputs and get their properties.

Implementations

impl OutputHandle

pub fn from_name(name: impl ToString) -> Self

Creates an output handle from a name.

pub fn set_loc(&self, x: i32, y: i32)

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 leave space between two outputs when setting their locations, the pointer will not be able to move between them.

Examples

// 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:
//   x=0    ┌───────┐y=-360
// y=0┌─────┤       │
//    │DP-1 │HDMI-1 │
//    └─────┴───────┘
//          ^x=1920

pub fn set_loc_adj_to(&self, other: &OutputHandle, alignment: Alignment)

Sets this output adjacent to another one.

This is a helper method over OutputHandle::set_loc to make laying out outputs easier.

alignment is an Alignment of how you want this output to be placed. For example, TopAlignLeft will place this output above other and align the left borders. Similarly, RightAlignCenter will place this output to the right of other and align their centers.

Examples

// Assume two monitors in order, "DP-1" and "HDMI-1", with the following dimensions:
//  - "DP-1":   ┌─────┐
//              │     │1920x1080
//              └─────┘
//  - "HDMI-1": ┌───────┐
//              │ 2560x │
//              │ 1440  │
//              └───────┘
let dp_1 = output::get_by_name("DP-1")?;
let hdmi_1 = output::get_by_name("HDMI-1")?;
dp_1.set_loc_adj_to(&hdmi_1, Alignment::BottomAlignRight);
// 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.

pub fn set_mode( &self, width: u32, height: u32, refresh_rate_mhz: impl Into<Option<u32>>, )

Sets this output’s mode.

If refresh_rate_mhz is provided, Pinnacle will attempt to use the mode with that refresh rate. If it is not, Pinnacle will attempt to use the mode with the highest refresh rate that matches the given size.

The refresh rate should be given in millihertz. For example, if you want a refresh rate of 60Hz, use 60000.

If this output doesn’t support the given mode, it will be ignored.

Examples

// Sets the focused output to 2560x1440 at 144Hz
output::get_focused()?.set_mode(2560, 1440, 144000);

pub fn set_custom_mode( &self, width: u32, height: u32, refresh_rate_mhz: impl Into<Option<u32>>, )

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 is not, it will default to 60Hz.

The refresh rate should be given in millihertz. For example, if you want a refresh rate of 60Hz, use 60000.

Examples

// Sets the focused output to 2560x1440 at 75Hz
output::get_focused()?.set_custom_mode(2560, 1440, 75000);

pub fn set_modeline(&self, modeline: Modeline)

Sets a custom modeline for this output.

See xorg.conf(5) for more information.

You can parse a modeline from a string of the form “<clock> <hdisplay> <hsync_start> <hsync_end> <htotal> <vdisplay> <vsync_start> <vsync_end> <hsync> <vsync>”.

Examples

let output = output::get_focused()?;
output.set_modeline("173.00 1920 2048 2248 2576 1080 1083 1088 1120 -hsync +vsync".parse().unwrap());

pub fn set_scale(&self, scale: f32)

Sets this output’s scaling factor.

pub fn change_scale(&self, change_by: f32)

Changes this output’s scaling factor by a relative amount.

Examples

output::get_focused()?.change_scale(0.25);
output::get_focused()?.change_scale(-0.25);

pub fn set_transform(&self, transform: Transform)

Sets this output’s Transform.

Examples

// Rotate 90 degrees counter-clockwise
output::get_focused()?.set_transform(Transform::_90);

pub fn set_powered(&self, powered: bool)

Powers on or off this output.

This will not remove it from the space and your tags and windows will still be interactable; only the monitor is turned off.

pub fn toggle_powered(&self)

Toggles the power on this output.

This will not remove it from the space and your tags and windows will still be interactable; only the monitor is turned off.

pub fn make(&self) -> String

Gets this output’s make.

pub async fn make_async(&self) -> String

Async impl for Self::make.

pub fn model(&self) -> String

Gets this output’s model.

pub async fn model_async(&self) -> String

Async impl for Self::model.

pub fn serial(&self) -> String

Gets this output’s serial.

pub async fn serial_async(&self) -> String

Async impl for Self::serial.

pub fn loc(&self) -> Option<Point>

Gets this output’s location in the global space.

May return None if it is disabled.

pub async fn loc_async(&self) -> Option<Point>

Async impl for Self::loc.

pub fn logical_size(&self) -> Option<Size>

Gets this output’s logical size in logical pixels.

If this output has a scale of 1, this will equal the output’s actual pixel size. If it has a scale of 2, it will have half the logical pixel width and height. Similarly, if it has a scale of 0.5, it will have double the logical pixel width and height.

May return None if it is disabled.

pub async fn logical_size_async(&self) -> Option<Size>

Async impl for Self::logical_size.

pub fn current_mode(&self) -> Option<Mode>

Gets this output’s current mode.

May return None if it is disabled.

pub async fn current_mode_async(&self) -> Option<Mode>

Async impl for Self::current_mode.

pub fn preferred_mode(&self) -> Option<Mode>

Gets this output’s preferred mode.

May return None if it is disabled.

pub async fn preferred_mode_async(&self) -> Option<Mode>

Async impl for Self::preferred_mode.

pub fn modes(&self) -> impl Iterator<Item = Mode>

Gets all modes currently known to this output.

pub async fn modes_async(&self) -> impl Iterator<Item = Mode>

Async impl for Self::modes.

pub fn physical_size(&self) -> Size

Gets this output’s physical size in millimeters.

Returns a size of (0, 0) if unknown.

pub async fn physical_size_async(&self) -> Size

Async impl for Self::physical_size.

pub fn focused(&self) -> bool

Gets whether or not this output is focused.

This is currently implemented as the output with the most recent pointer motion.

pub async fn focused_async(&self) -> bool

Async impl for Self::focused.

pub fn tags(&self) -> impl Iterator<Item = TagHandle>

Gets handles to all tags on this output.

pub async fn tags_async(&self) -> impl Iterator<Item = TagHandle>

Async impl for Self::tags.

pub fn scale(&self) -> f32

Gets this output’s current scale.

pub async fn scale_async(&self) -> f32

Async impl for Self::scale.

pub fn transform(&self) -> Transform

Gets this output’s current transform.

pub async fn transform_async(&self) -> Transform

Async impl for Self::transform.

pub fn keyboard_focus_stack(&self) -> impl Iterator<Item = WindowHandle>

Gets this window’s keyboard focus stack.

Pinnacle keeps a stack of the windows that get keyboard focus. This can be used, for example, for an Alt + Tab-style keybind that focuses the previously focused window.

This will return the focus stack containing all windows on this output. If you only want windows on active tags, see OutputHandle::keyboard_focus_stack_visible.

pub async fn keyboard_focus_stack_async( &self, ) -> impl Iterator<Item = WindowHandle>

Async impl for Self::keyboard_focus_stack.

pub fn keyboard_focus_stack_visible(&self) -> impl Iterator<Item = WindowHandle>

Gets this window’s keyboard focus stack with only windows on active tags.

Pinnacle keeps a stack of the windows that get keyboard focus. This can be used, for example, for an Alt + Tab-style keybind that focuses the previously focused window.

This will return the focus stack containing only windows on active tags on this output. If you want all windows on this output, see OutputHandle::keyboard_focus_stack.

pub async fn keyboard_focus_stack_visible_async( &self, ) -> impl Iterator<Item = WindowHandle>

Async impl for Self::keyboard_focus_stack_visible.

pub fn enabled(&self) -> bool

Gets whether this output is enabled.

pub async fn enabled_async(&self) -> bool

Async impl for Self::enabled.

pub fn powered(&self) -> bool

Gets whether or not this output is powered.

Unpowered outputs are turned off but you can still interact with them.

pub async fn powered_async(&self) -> bool

Async impl for Self::powered.

pub fn name(&self) -> String

Returns this output’s unique name (the name of its connector).

Trait Implementations

impl Clone for OutputHandle

fn clone(&self) -> OutputHandle

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for OutputHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for OutputHandle

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for OutputHandle

fn eq(&self, other: &OutputHandle) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for OutputHandle

impl StructuralPartialEq for OutputHandle