XfwMonitor: libxfce4windowing Reference Manual

## XfwMonitor XfwMonitor — An object representing a physical monitor |

## Stability Level

Unstable, unless otherwise indicated

## Functions

const char * | xfw_monitor_get_identifier ()
const char * | xfw_monitor_get_description ()
const char * | xfw_monitor_get_connector ()
const char * | xfw_monitor_get_make ()
const char * | xfw_monitor_get_model ()
const char * | xfw_monitor_get_serial ()
guint | xfw_monitor_get_refresh ()
guint | xfw_monitor_get_scale ()
gdouble | xfw_monitor_get_fractional_scale ()
void | xfw_monitor_get_physical_geometry ()
void | xfw_monitor_get_logical_geometry ()
void | xfw_monitor_get_workarea ()
void | xfw_monitor_get_physical_size ()
XfwMonitorSubpixel | xfw_monitor_get_subpixel ()
XfwMonitorTransform | xfw_monitor_get_transform ()
gboolean | xfw_monitor_is_primary ()
GdkMonitor * | xfw_monitor_get_gdk_monitor ()

## Properties

char * | connector | Read
char * | description | Read
double | fractional-scale | Read
GdkMonitor * | gdk-monitor | Read
guint | height-mm | Read
char * | identifier | Read
gboolean | is-primary | Read
GdkRectangle * | logical-geometry | Read
char * | make | Read
char * | model | Read
GdkRectangle * | physical-geometry | Read
guint | refresh | Read
guint | scale | Read
char * | serial | Read
XfwMonitorSubpixel | subpixel | Read
XfwMonitorTransform | transform | Read
guint | width-mm | Read
GdkRectangle * | workarea | Read

## Types and Values

| XfwMonitor
enum | XfwMonitorSubpixel
enum | XfwMonitorTransform

## Object Hierarchy

        GEnum
        ├── XfwMonitorSubpixel
        ╰── XfwMonitorTransform
        GObject
        ╰── XfwMonitor

## Includes

    #include <libxfce4windowing/libxfce4windowing.h>

## Description

XfwMonitor represents a physical monitor connected to the XfwScreen.

In some virtual environments (e.g. a nested X11 or Wayland session), the monitor might instead represent an on-screen window that contains the output of the virtual environment.

## Functions

### xfw_monitor_get_identifier ()

    const char *
    xfw_monitor_get_identifier (XfwMonitor *monitor);

Retrieves an opaque identifier for this monitor. The identifier can usually be relied upon to uniquely identify this monitor (even if you have multiple identical monitors of the same make and model), assuming the monitor's hardware is set up properly.

This identifier should also be stable across application and machine restarts.

If the monitor's hardware is not set up properly, the identifier may not be unique. Unfortunately, this library cannot determine when this is the case.

#### Parameters

monitor | a XfwMonitor. |

#### Returns

A string owned by `monitor` .

[not nullable][transfer none]

Since: 4.19.4

### xfw_monitor_get_description ()

    const char *
    xfw_monitor_get_description (XfwMonitor *monitor);

Returns a human-readable description of this monitor, suitable for displaying in a user interface.

#### Parameters

monitor | a XfwMonitor. |

#### Returns

A string owned by `monitor` .

[not nullable][transfer none]

Since: 4.19.4

### xfw_monitor_get_connector ()

    const char *
    xfw_monitor_get_connector (XfwMonitor *monitor);

Returns the name of the physical connector this monitor is connected to.

This might be a string such as "eDP-1", "DP-3", or "HDMI-2". Note that in environments where the monitor is "virtual", a synthetic connector name may be returned.

#### Parameters

monitor | a XfwMonitor. |

#### Returns

A string owned by `monitor` .

[not nullable][transfer none]

Since: 4.19.4

### xfw_monitor_get_make ()

    const char *
    xfw_monitor_get_make (XfwMonitor *monitor);

Returns the monitor's manufacturer's name, if available.

#### Parameters

monitor | a XfwMonitor. |

#### Returns

A string owned by `monitor` , or `NULL`.

[nullable][transfer none]

Since: 4.19.4

### xfw_monitor_get_model ()

    const char *
    xfw_monitor_get_model (XfwMonitor *monitor);

Returns the monitor's product model name, if available.

#### Parameters

monitor | a XfwMonitor. |

#### Returns

A string owned by `monitor` , or `NULL`.

[nullable][transfer none]

Since: 4.19.4

### xfw_monitor_get_serial ()

    const char *
    xfw_monitor_get_serial (XfwMonitor *monitor);

Returns the monitor's serial number, if available. Note that some manufacturers do not program their monitor's hardware with unique serial numbers.

#### Parameters

monitor | a XfwMonitor. |

#### Returns

A string owned by `monitor` , or `NULL`.

[nullable][transfer none]

Since: 4.19.4

### xfw_monitor_get_refresh ()

    guint
    xfw_monitor_get_refresh (XfwMonitor *monitor);

Returns the monitor's current refresh rate, in millihertz.

#### Parameters

monitor | a XfwMonitor. |

#### Returns

A non-negative integer in mHz.

Since: 4.19.4

### xfw_monitor_get_scale ()

    guint
    xfw_monitor_get_scale (XfwMonitor *monitor);

Returns the monitor's scaling factor, as an integer.

#### Parameters

monitor | a XfwMonitor. |

#### Returns

A positive integer scale.

Since: 4.19.4

### xfw_monitor_get_fractional_scale ()

    gdouble
    xfw_monitor_get_fractional_scale (XfwMonitor *monitor);

Returns the monitor's scaling factor.

#### Parameters

monitor | a XfwMonitor. |

#### Returns

A positive fractional scale.

Since: 4.19.4

### xfw_monitor_get_physical_geometry ()

    void
    xfw_monitor_get_physical_geometry (XfwMonitor *monitor,
                                       GdkRectangle *physical_geometry);

Retrieves the position and size of the monitor in physical device pixels.

#### Parameters

monitor | a XfwMonitor. |
physical_geometry | a GdkRectangle. | [not nullable][out caller-allocates]

Since: 4.19.4

### xfw_monitor_get_logical_geometry ()

    void
    xfw_monitor_get_logical_geometry (XfwMonitor *monitor,
                                      GdkRectangle *logical_geometry);

Retrieves the position and size of the monitor in logical application pixels, which are affected by the monitor's fractional scale factor.

#### Parameters

monitor | a XfwMonitor. |
logical_geometry | a GdkRectangle. | [not nullable][out caller-allocates]

Since: 4.19.4

### xfw_monitor_get_workarea ()

    void
    xfw_monitor_get_workarea (XfwMonitor *monitor,
                              GdkRectangle *workarea);

Retrieves the workarea for `monitor` , which may exclude regions of the screen for windows such as panels or docks.

The returned geometry is in logical application pixels, which are affected by the monitor's integer scale factor. The origin is set to the top-left corner of the monitor.

#### Parameters

monitor | a XfwMonitor. |
workarea | a GdkRectangle. | [not nullable][out caller-allocates]

Since: 4.19.4

### xfw_monitor_get_physical_size ()

    void
    xfw_monitor_get_physical_size (XfwMonitor *monitor,
                                   guint *width_mm,
                                   guint *height_mm);

Retrieves the physical width and height of the monitor in millimeters.

#### Parameters

monitor | a XfwMonitor. |
width_mm | an unsigned integer. | [nullable][out caller-allocates]
height_mm | an unsigned integer. | [nullable][out caller-allocates]

Since: 4.19.4

### xfw_monitor_get_subpixel ()

    XfwMonitorSubpixel
    xfw_monitor_get_subpixel (XfwMonitor *monitor);

Returns the subpixel ordering of `monitor` .

#### Parameters

monitor | a XfwMonitor. |

#### Returns

A value from the XfwMonitorSubpixel enum.

Since: 4.19.4

### xfw_monitor_get_transform ()

    XfwMonitorTransform
    xfw_monitor_get_transform (XfwMonitor *monitor);

Returns the rotation and reflection transform set on `monitor` .

#### Parameters

monitor | a XfwMonitor. |

#### Returns

A value from the XfwMonitorTransform enum.

Since: 4.19.4

### xfw_monitor_is_primary ()

    gboolean
    xfw_monitor_is_primary (XfwMonitor *monitor);

Returns whether or not `monitor` has been designated as the primary monitor.

#### Parameters

monitor | a XfwMonitor. |

#### Returns

`TRUE` or `FALSE`.

Since: 4.19.4

### xfw_monitor_get_gdk_monitor ()

    GdkMonitor *
    xfw_monitor_get_gdk_monitor (XfwMonitor *monitor);

Returns the GdkMonitor that corresponds to `monitor` .

#### Parameters

monitor | a XfwMonitor. |

#### Returns

A GdkMonitor.

[not nullable][transfer none]

Since: 4.19.4

## Types and Values

### XfwMonitor

    typedef struct _XfwMonitor XfwMonitor;

### enum XfwMonitorSubpixel

Describes how the color components of the physical pixels are laid out on a monitor.

#### Members

XFW_MONITOR_SUBPIXEL_UNKNOWN | unknown subpixel ordering. |
XFW_MONITOR_SUBPIXEL_NONE | no subpixel geometry. |
XFW_MONITOR_SUBPIXEL_HRGB | horizontal RGB. |
XFW_MONITOR_SUBPIXEL_HBGR | horizontal BGR. |
XFW_MONITOR_SUBPIXEL_VRGB | vertical RGB. |
XFW_MONITOR_SUBPIXEL_VBGR | vertical BGR. |

Since: 4.19.4

### enum XfwMonitorTransform

Describes the rotation and reflection applied to a monitor.

#### Members

XFW_MONITOR_TRANSFORM_NORMAL | no transformation applied. |
XFW_MONITOR_TRANSFORM_90 | rotated counter-clockwise by 90 degrees. |
XFW_MONITOR_TRANSFORM_180 | rotated counter-clockwise by 180 degrees. |
XFW_MONITOR_TRANSFORM_270 | rotated counter-clockwise by 270 degrees. |
XFW_MONITOR_TRANSFORM_FLIPPED | flipped along a vertical axis. |
XFW_MONITOR_TRANSFORM_FLIPPED_90 | flipped along a vertical axis and rotated counter-clockwise by 90 degrees. |
XFW_MONITOR_TRANSFORM_FLIPPED_180 | flipped along a vertical axis and rotated counter-clockwise by 180 degrees. |
XFW_MONITOR_TRANSFORM_FLIPPED_270 | flipped along a vertical axis and rotated counter-clockwise by 270 degrees. |

Since: 4.19.4

## Property Details

### The `“connector”` property

      “connector”                char *

Physical/virtual connector name.

Owner: XfwMonitor

Flags: Read

Default value: NULL

Since: 4.19.4

### The `“description”` property

      “description”              char *

Human-readable description.

Owner: XfwMonitor

Flags: Read

Default value: NULL

Since: 4.19.4

### The `“fractional-scale”` property

      “fractional-scale”         double

UI fractional scaling factor.

Owner: XfwMonitor

Flags: Read

Allowed values: >= 1

Default value: 1

Since: 4.19.4

### The `“gdk-monitor”` property

      “gdk-monitor”              GdkMonitor *

The GdkMonitor corresponding to this monitor.

Since 4.19.4

Owner: XfwMonitor

Flags: Read

### The `“height-mm”` property

      “height-mm”                guint

Physical height of the monitor in millimeters.

Owner: XfwMonitor

Flags: Read

Default value: 0

Since: 4.19.4

### The `“identifier”` property

      “identifier”               char *

Opaque, hopefully-unique monitor identifier.

Owner: XfwMonitor

Flags: Read

Default value: NULL

Since: 4.19.4

### The `“is-primary”` property

      “is-primary”               gboolean

Whether or not this monitor is the primary monitor.

Owner: XfwMonitor

Flags: Read

Default value: FALSE

Since: 4.19.4

### The `“logical-geometry”` property

      “logical-geometry”         GdkRectangle *

Coordinates and size of the monitor in scaled logical pixels.

Owner: XfwMonitor

Flags: Read

Since: 4.19.4

### The `“make”` property

      “make”                     char *

Manufacturer name.

Owner: XfwMonitor

Flags: Read

Default value: NULL

Since: 4.19.4

### The `“model”` property

      “model”                    char *

Product model name.

Owner: XfwMonitor

Flags: Read

Default value: NULL

Since: 4.19.4

### The `“physical-geometry”` property

      “physical-geometry”        GdkRectangle *

Coordinates and size of the monitor in physical device pixels.

Owner: XfwMonitor

Flags: Read

Since: 4.19.4

### The `“refresh”` property

      “refresh”                  guint

Current refresh rate, in millihertz.

Owner: XfwMonitor

Flags: Read

Default value: 60000

Since: 4.19.4

### The `“scale”` property

      “scale”                    guint

UI scaling factor.

Owner: XfwMonitor

Flags: Read

Allowed values: >= 1

Default value: 1

Since: 4.19.4

### The `“serial”` property

      “serial”                   char *

Product serial number.

Owner: XfwMonitor

Flags: Read

Default value: NULL

Since: 4.19.4

### The `“subpixel”` property

      “subpixel”                 XfwMonitorSubpixel

Hardware subpixel layout.

Owner: XfwMonitor

Flags: Read

Default value: XFW_MONITOR_SUBPIXEL_UNKNOWN

Since: 4.19.4

### The `“transform”` property

      “transform”                XfwMonitorTransform

Rotation and reflection of the monitor's contents.

Owner: XfwMonitor

Flags: Read

Default value: XFW_MONITOR_TRANSFORM_NORMAL

### The `“width-mm”` property

      “width-mm”                 guint

Physical width of the monitor in millimeters.

Owner: XfwMonitor

Flags: Read

Default value: 0

Since: 4.19.4

### The `“workarea”` property

      “workarea”                 GdkRectangle *

Monitor workarea in scaled logical pixels.

Owner: XfwMonitor

Flags: Read