struct Espresso::Monitor

Overview

Reference to a display monitor or screen and information about it.

Instances of this type cannot be created by the end-user. To retrieve a monitor, use the #primary or #all methods.

Included Modules

Defined in:

espresso/monitor.cr

Class Method Summary

Instance Method Summary

Class Method Detail

def self.all #

Retrieves all of the monitors connected to the user's system. This returns an array of Monitor instances.

The primary monitor is always the first monitor in the returned array, but other monitors may be moved to a different index when a monitor is connected or disconnected.


[View source]
def self.on_connect(&block : self -> ) #

Registers a listener to respond when a monitor is connected. The block of code passed to this method will be invoked when a monitor is connected. The monitor instance will be provided as an argument to the block. To remove the listener, call #remove_connect_listener with the proc returned by this method.


[View source]
def self.on_disconnect(&block : self -> ) #

Registers a listener to respond when any monitor is disconnected. The block of code passed to this method will be invoked when a monitor is disconnected. The monitor instance will be provided as an argument to the block. To remove the listener, call #remove_disconnect_listener with the proc returned by this method.


[View source]
def self.primary #

Retrieves the user's primary monitor. If there are no monitors, then a NilAssertionError will be raised.


[View source]
def self.primary? #

Attempts to retrieve the user's primary monitor. If there's no monitors, then this returns nil.


[View source]
def self.remove_connect_listener(proc : self -> ) : Nil #

Removes a previously registered listener that responded when a monitor is connected. The proc argument should be the return value of the #on_connect method.


[View source]
def self.remove_disconnect_listener(proc : self -> ) : Nil #

Removes a previously registered listener that responded when a monitor is disconnected. The proc argument should be the return value of the #on_disconnect method.


[View source]

Instance Method Detail

def content_scale #

Ratio between the current DPI and the platform's default DPI. This is especially important for text and any UI elements. If the pixel dimensions of your UI scaled by this look appropriate on your machine then it should appear at a reasonable size on other machines regardless of their DPI and scaling settings. This relies on the system DPI and scaling settings being somewhat correct.

The content scale may depend on both the monitor resolution and pixel density and on user settings. It may be very different from the raw DPI calculated from the physical size and current resolution.

Can raise a PlatformError.

See also: Window#content_scale


[View source]
def current_video_mode #

Retrieves the currently active video mode for the monitor.

If there is a full-screen window, and it isn't iconified, the video mode returned will match the window's video mode.

Can raise a PlatformError.


[View source]
def gamma=(gamma) #

Adjusts the gamma ramp for the monitor. The gamma argument is the desired exponent. GLFW will compute a normal gamma ramp and apply it.

The software controlled gamma ramp is applied in addition to the hardware gamma correction, which today is usually an approximation of sRGB gamma. This means that setting a perfectly linear ramp, or gamma 1.0, will produce the default (usually sRGB-like) behavior.

Can raise a PlatformError. Raises an ArgumentError if the gamma value is invalid.


[View source]
def gamma_ramp #

Retrieves the current gamma ramp for the monitor.

On Wayland, gamma handling is a priviledged protocol, and this method will always raise PlatformError.

Can raise a PlatformError.


[View source]
def gamma_ramp=(ramp) #

Sets the gamma ramp to be used for the monitor. The original gamma ramp for that monitor is saved by GLFW the first time this function is called and is restored when GLFW is terminated (Espresso.terminate).

The software controlled gamma ramp is applied in addition to the hardware gamma correction, which today is usually an approximation of sRGB gamma. This means that setting a perfectly linear ramp, or gamma 1.0, will produce the default (usually sRGB-like) behavior.

For gamma correct rendering with OpenGL or OpenGL ES, see the GLFW_SRGB_CAPABLE hint.

The size of the specified gamma ramp should match the size of the current ramp for this monitor. On Windows, the gamma ramp size must be 256. On Wayland, gamma handling is a priviledged protocol, and this method will always raise PlatformError.

Can raise a PlatformError.


[View source]
def name #

Retrieves the human-readable name of the monitor. The name typically reflects the make and model of the monitor and is not guaranteed to be unique among the connected monitors.

Only the monitor handle is guaranteed to be unique, and only until that monitor is disconnected. If you want to compare monitors, use the == operator.


[View source]
def on_disconnect(&block : self -> ) #

Registers a listener to respond when this monitor is disconnected. The block of code passed to this method will be invoked when the monitor is disconnected. The monitor instance (this) will be provided as an argument to the block. To remove the listener, call #remove_disconnect_listener with the proc returned by this method. All registered listeners will be automatically removed after they have been called and this monitor is disconnected.


[View source]
def physical_size #

Physical size of a monitor in millimetres, or an estimation of it.

While this can be used to calculate the raw DPI of a monitor, this is often not useful. Instead use #content_scale and Window#content_scale to scale your content.

Some systems do not provide accurate monitor size information, either because the monitor EDID data is incorrect or because the driver does not report it accurately. On Windows, the physical size is calculated from the current resolution and system DPI instead of querying the monitor EDID data.


[View source]
def position #

Position, in screen coordinates, of the upper-left corner of the monitor. This is the position of the monitor on the virtual desktop.

Can raise a PlatformError.


[View source]
def remove_disconnect_listener(proc : self -> ) : Nil #

Removes a previously registered listener that responded when this monitor is disconnected. The proc argument should be the return value of the #on_disconnect method.


[View source]
def size #

Size, in screen coordinates, of the monitor.

Can raise a PlatformError.


[View source]
def to_s(io) #

String representation of the monitor.


[View source]
def to_unsafe : LibGLFW::Monitor #

Returns the underlying GLFW monitor pointer.


[View source]
def user_pointer #

Retrieves the current value of the user-defined pointer for this monitor. This can be used for any purpose you need and will not be modified by GLFW. The value will be kept until the monitor is disconnected or until the library is terminated. The initial value is nil.

This method may be called from the monitor connect/disconnect event, even if the monitor is being disconnected.


[View source]
def user_pointer=(pointer) #

Updates the value of the user-defined pointer for this monitor. This can be used for any purpose you need and will not be modified by GLFW. The value will be kept until the monitor is disconnected or until the library is terminated. The initial value is nil.


[View source]
def video_modes #

List of all video modes supported by the monitor. The returned array is sorted in ascending order, first by color bit depth (the sum of all channel depths) and then by resolution area (the product of width and height).

Can raise a PlatformError.


[View source]
def workarea #

Area of a monitor not occupied by global task bars or menu bars. This is specified in screen coordinates.

Can raise a PlatformError.


[View source]