The cl-monitors Reference Manual

Table of Contents

The cl-monitors Reference Manual

This is the cl-monitors Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 15:03:57 2021 GMT+0.

1 Introduction

About cl-monitors

This is a small wrapper library around libmonitors, providing independent monitor resolution detection and change support.

How To

Precompiled versions of the underlying library are included in this. If you want to build it manually however, refer to the libmonitors README.

Load the system through ASDF or Quicklisp and initialise it:

(ql:quickload :cl-monitors)
(cl-monitors:init)

Now you can retrieve a list of the monitors on your system:

(cl-monitors:detect)

You can inspect the available video modes for each of them too:

(mapcar #'cl-monitors:modes *)

And even switch the mode:

(cl-monitors:make-current (second (first *)))

Though you probably want to switch back again to your preferred resolution:

(cl-monitors:make-current (first (first **)))

Once you're all done, don't forget to clean up again after yourself:

(cl-monitors:deinit)

And that's all there is to it. Well-- almost all. You can query information from the monitor and mode objects as well of course. For this, see width, height, refresh, current-p, mode, name, and primary-p.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 cl-monitors

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://Shirakumo.github.io/cl-monitors/

Source Control

(:git "https://github.com/shirakumo/cl-monitors.git")

Bug Tracker

https://github.com/Shirakumo/cl-monitors/issues

License

zlib

Description

Bindings to libmonitors, allowing the handling of monitors querying and resolution changing.

Version

1.0.0

Dependencies

• cffi
• trivial-features
• trivial-garbage
• documentation-utils

Source

cl-monitors.asd (file)

Components

• package.lisp (file)
• low-level.lisp (file)
• wrapper.lisp (file)
• documentation.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 cl-monitors.asd

Location

cl-monitors.asd

Systems

cl-monitors (system)

3.1.2 cl-monitors/package.lisp

Parent

cl-monitors (system)

Location

package.lisp

Packages

• cl-monitors-cffi
• cl-monitors

3.1.3 cl-monitors/low-level.lisp

Dependency

package.lisp (file)

Parent

cl-monitors (system)

Location

low-level.lisp

Exported Definitions

• *static* (special variable)
• mode-data (function)
• (setf mode-data) (function)
• mode-height (function)
• (setf mode-height) (function)
• mode-monitor (function)
• (setf mode-monitor) (function)
• mode-refresh (function)
• (setf mode-refresh) (function)
• mode-struct (class)
• mode-width (function)
• (setf mode-width) (function)
• monitor-current-mode (function)
• (setf monitor-current-mode) (function)
• monitor-data (function)
• (setf monitor-data) (function)
• monitor-height (function)
• (setf monitor-height) (function)
• monitor-mode-count (function)
• (setf monitor-mode-count) (function)
• monitor-modes (function)
• (setf monitor-modes) (function)
• monitor-name (function)
• (setf monitor-name) (function)
• monitor-primary (function)
• (setf monitor-primary) (function)
• monitor-struct (class)
• monitor-width (function)
• (setf monitor-width) (function)
• monitors-deinit (function)
• monitors-detect (function)
• monitors-free-monitor (function)
• monitors-free-monitors (function)
• monitors-init (function)
• monitors-make-mode-current (function)

Internal Definitions

*here* (special variable)

3.1.4 cl-monitors/wrapper.lisp

Dependency

low-level.lisp (file)

Parent

cl-monitors (system)

Location

wrapper.lisp

Exported Definitions

• current-p (method)
• deinit (function)
• detect (function)
• detection-failed-error (condition)
• height (method)
• height (method)
• init (function)
• initialization-failed-error (condition)
• make-current (function)
• mode (method)
• mode (method)
• (setf mode) (method)
• mode (class)
• mode-switch-failed-error (condition)
• modes (method)
• monitor (method)
• monitor (class)
• monitor-condition (condition)
• name (method)
• primary-p (method)
• refresh (method)
• width (method)
• width (method)

Internal Definitions

• define-foreign-reader (macro)
• foreign-object (class)
• pointer (method)

3.1.5 cl-monitors/documentation.lisp

Dependency

wrapper.lisp (file)

Parent

cl-monitors (system)

Location

documentation.lisp

4 Packages

Packages are listed by definition order.

4.1 cl-monitors-cffi

Source

package.lisp (file)

Nickname

org.shirakumo.fraf.monitors.cffi

Use List

• cffi
• common-lisp

Used By List

cl-monitors

Exported Definitions

• *static* (special variable)
• mode-data (function)
• (setf mode-data) (function)
• mode-height (function)
• (setf mode-height) (function)
• mode-monitor (function)
• (setf mode-monitor) (function)
• mode-refresh (function)
• (setf mode-refresh) (function)
• mode-struct (class)
• mode-width (function)
• (setf mode-width) (function)
• monitor-current-mode (function)
• (setf monitor-current-mode) (function)
• monitor-data (function)
• (setf monitor-data) (function)
• monitor-height (function)
• (setf monitor-height) (function)
• monitor-mode-count (function)
• (setf monitor-mode-count) (function)
• monitor-modes (function)
• (setf monitor-modes) (function)
• monitor-name (function)
• (setf monitor-name) (function)
• monitor-primary (function)
• (setf monitor-primary) (function)
• monitor-struct (class)
• monitor-width (function)
• (setf monitor-width) (function)
• monitors-deinit (function)
• monitors-detect (function)
• monitors-free-monitor (function)
• monitors-free-monitors (function)
• monitors-init (function)
• monitors-make-mode-current (function)

Internal Definitions

*here* (special variable)

4.2 cl-monitors

Source

package.lisp (file)

Nickname

org.shirakumo.fraf.monitors

Use List

• cl-monitors-cffi
• common-lisp

Exported Definitions

• current-p (generic function)
• current-p (method)
• deinit (function)
• detect (function)
• detection-failed-error (condition)
• height (generic function)
• height (method)
• height (method)
• init (function)
• initialization-failed-error (condition)
• make-current (function)
• mode (generic function)
• mode (method)
• mode (method)
• (setf mode) (generic function)
• (setf mode) (method)
• mode (class)
• mode-switch-failed-error (condition)
• modes (generic function)
• modes (method)
• monitor (generic function)
• monitor (method)
• monitor (class)
• monitor-condition (condition)
• name (generic function)
• name (method)
• primary-p (generic function)
• primary-p (method)
• refresh (generic function)
• refresh (method)
• width (generic function)
• width (method)
• width (method)

Internal Definitions

• define-foreign-reader (macro)
• foreign-object (class)
• pointer (generic function)
• pointer (method)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *static*

Variable containing a pathname to the static directory.

Package

cl-monitors-cffi

Source

low-level.lisp (file)

5.1.2 Functions

Function: deinit ()

Cleans up the library.

You should call this once you are done with everything.

Package

cl-monitors

Source

wrapper.lisp (file)

Function: detect ()

Detects the monitors and modes on the system.

Returns a list of monitors on the system. Signals a DETECTION-FAILED-ERROR on failured.

See MONITOR

Package

cl-monitors

Source

wrapper.lisp (file)

Function: init ()

Initializes the library.

You should call this before any other function to the library is called. Signals an INITIALIZATION-FAILED-ERROR on failure.

Package

cl-monitors

Source

wrapper.lisp (file)

Function: make-current MODE

Attempts to make the passed mode the current one.

This is equivalent to doing (SETF (MODE (MONITOR mode)) mode).

See MODE

Package

cl-monitors

Source

wrapper.lisp (file)

Function: mode-data POINTER-TO-MODE-STRUCT

Reads the pointer to the system-dependant data struct of the mode.

You should not need this for anything.

See MODE-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Writer

(setf mode-data) (function)

Function: (setf mode-data) VALUE POINTER-TO-MODE-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Reader

mode-data (function)

Function: mode-height POINTER-TO-MODE-STRUCT

Reads the mode’s height in pixels.

See MODE-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Writer

(setf mode-height) (function)

Function: (setf mode-height) VALUE POINTER-TO-MODE-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Reader

mode-height (function)

Function: mode-monitor POINTER-TO-MODE-STRUCT

Reads the pointer to the monitor struct this mode originated from.

See MODE-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Writer

(setf mode-monitor) (function)

Function: (setf mode-monitor) VALUE POINTER-TO-MODE-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Reader

mode-monitor (function)

Function: mode-refresh POINTER-TO-MODE-STRUCT

Reads the mode’s refresh rate in Herz.

See MODE-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Writer

(setf mode-refresh) (function)

Function: (setf mode-refresh) VALUE POINTER-TO-MODE-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Reader

mode-refresh (function)

Function: mode-width POINTER-TO-MODE-STRUCT

Reads the mode’s width in pixels.

See MODE-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Writer

(setf mode-width) (function)

Function: (setf mode-width) VALUE POINTER-TO-MODE-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Reader

mode-width (function)

Function: monitor-current-mode POINTER-TO-MONITOR-STRUCT

Reads the pointer to the current mode of the monitor.

See MONITOR-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Writer

(setf monitor-current-mode) (function)

Function: (setf monitor-current-mode) VALUE POINTER-TO-MONITOR-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Reader

monitor-current-mode (function)

Function: monitor-data POINTER-TO-MONITOR-STRUCT

Reads the pointer to the system-dependant data struct of the monitor.

You should not need this for anything.

See MONITOR-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Writer

(setf monitor-data) (function)

Function: (setf monitor-data) VALUE POINTER-TO-MONITOR-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Reader

monitor-data (function)

Function: monitor-height POINTER-TO-MONITOR-STRUCT

Reads the monitor’s physical height in millimetres.

See MONITOR-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Writer

(setf monitor-height) (function)

Function: (setf monitor-height) VALUE POINTER-TO-MONITOR-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Reader

monitor-height (function)

Function: monitor-mode-count POINTER-TO-MONITOR-STRUCT

Reads the count for how many mode structs there are in the mode field of the monitor.

See MONITOR-MODES
See MONITOR-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Writer

(setf monitor-mode-count) (function)

Function: (setf monitor-mode-count) VALUE POINTER-TO-MONITOR-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Reader

monitor-mode-count (function)

Function: monitor-modes POINTER-TO-MONITOR-STRUCT

Reads the pointer to the packed mode struct array of the monitor.

See MONITOR-MODE-COUNT
See MONITOR-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Writer

(setf monitor-modes) (function)

Function: (setf monitor-modes) VALUE POINTER-TO-MONITOR-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Reader

monitor-modes (function)

Function: monitor-name POINTER-TO-MONITOR-STRUCT

Reads the monitor’s name string.

See MONITOR-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Writer

(setf monitor-name) (function)

Function: (setf monitor-name) VALUE POINTER-TO-MONITOR-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Reader

monitor-name (function)

Function: monitor-primary POINTER-TO-MONITOR-STRUCT

Reads whether the monitor is the primary monitor of the system.

See MONITOR-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Writer

(setf monitor-primary) (function)

Function: (setf monitor-primary) VALUE POINTER-TO-MONITOR-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Reader

monitor-primary (function)

Function: monitor-width POINTER-TO-MONITOR-STRUCT

Reads the monitor’s physical width in millimetres.

See MONITOR-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Writer

(setf monitor-width) (function)

Function: (setf monitor-width) VALUE POINTER-TO-MONITOR-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Reader

monitor-width (function)

Function: monitors-deinit ()

Cleans up the monitors library. You should call this once you are done with everything.

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Function: monitors-detect COUNT MONITORS

Detects the monitors and their modes on the system.

You need to pass this two "empty" pointers. The first will be set to
reference an int for the number of monitors that were detected, and the
second to an array of pointers to monitor structs.

If NIL is returned, the detection failed and the two pointers you passed will not have changed.

See MONITOR-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Function: monitors-free-monitor MONITOR

Frees a monitor struct.

See MONITOR-STRUCT

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Function: monitors-free-monitors COUNT MONITORS

Frees an array of pointers to monitor objects, including the monitors referenced by it.

See MONITORS-FREE-MONITOR

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Function: monitors-init ()

Initializes the monitors library. You should call this before anything.

If NIL is returned, the initialisation failed and other library calls will most likely too.

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Function: monitors-make-mode-current MODE

Attempts to make the given mode the current mode on its monitor.

If NIL is returned, the mode change failed. Otherwise the monitor’s current mode is updated to reflect the newly chose none.

See MODE-STRUCT
See MONITOR-CURRENT-MODE

Package

cl-monitors-cffi

Source

low-level.lisp (file)

5.1.3 Generic functions

Generic Function: current-p MODE

Returns whether the mode is the current mode of the monitor.

See MODE

Package

cl-monitors

Methods

Method: current-p (MODE mode)

Source

wrapper.lisp (file)

Generic Function: height MODE

Returns the height.

For a mode, this is in pixels.
For a monitor, this is in physical millimetres.

See MODE
See MONITOR

Package

cl-monitors

Methods

Method: height (MONITOR monitor)

Source

wrapper.lisp (file)

Method: height (MODE mode)

Source

wrapper.lisp (file)

Generic Function: mode CONDITION

Returns the current mode of the monitor.

SETFable. When set with a suitable mode, it will attempt to switch the current mode of the monitor to the new one.
Signals a MODE-SWITCH-FAILED-ERROR on failure.

See MODE
See MONITOR

Package

cl-monitors

Writer

(setf mode) (generic function)

Methods

Method: mode (MONITOR monitor)

automatically generated reader method

Source

wrapper.lisp (file)

Method: mode (CONDITION mode-switch-failed-error)

Source

wrapper.lisp (file)

Generic Function: (setf mode) MODE MONITOR

Package

cl-monitors

Reader

mode (generic function)

Methods

Method: (setf mode) (MODE mode) (MONITOR monitor)

Source

wrapper.lisp (file)

Generic Function: modes OBJECT

Returns the list of possible modes the monitor can assume.

A pox upon those that modify this list.

See MONITOR

Package

cl-monitors

Methods

Method: modes (MONITOR monitor)

automatically generated reader method

Source

wrapper.lisp (file)

Generic Function: monitor OBJECT

Returns the monitor the mode belongs to.

See MONITOR
See MODE

Package

cl-monitors

Methods

Method: monitor (MODE mode)

automatically generated reader method

Source

wrapper.lisp (file)

Generic Function: name MONITOR

Returns the monitor’s name on the system.

See MONITOR

Package

cl-monitors

Methods

Method: name (MONITOR monitor)

Source

wrapper.lisp (file)

Generic Function: primary-p MONITOR

Returns whether the monitor is the system’s primary monitor.

See MONITOR

Package

cl-monitors

Methods

Method: primary-p (MONITOR monitor)

Source

wrapper.lisp (file)

Generic Function: refresh MODE

Returns the mode’s refresh rate in Herz.

See MODE

Package

cl-monitors

Methods

Method: refresh (MODE mode)

Source

wrapper.lisp (file)

Generic Function: width MODE

Returns the width.

For a mode, this is in pixels.
For a monitor, this is in physical millimetres.

See MODE
See MONITOR

Package

cl-monitors

Methods

Method: width (MONITOR monitor)

Source

wrapper.lisp (file)

Method: width (MODE mode)

Source

wrapper.lisp (file)

5.1.4 Conditions

Condition: detection-failed-error ()

Condition for when the monitor detection fails.

See DETECT
See MONITOR-CONDITION

Package

cl-monitors

Source

wrapper.lisp (file)

Direct superclasses

• error (condition)
• monitor-condition (condition)

Condition: initialization-failed-error ()

Condition for when the monitor initialization fails.

See INIT
See MONITOR-CONDITION

Package

cl-monitors

Source

wrapper.lisp (file)

Direct superclasses

• error (condition)
• monitor-condition (condition)

Condition: mode-switch-failed-error ()

Condition for when the mode switch call fails.

See MODE
See MONITOR-CONDITION

Package

cl-monitors

Source

wrapper.lisp (file)

Direct superclasses

• error (condition)
• monitor-condition (condition)

Direct methods

mode (method)

Direct slots

Slot: mode

Initargs

:mode

Readers

mode (generic function)

Condition: monitor-condition ()

Base condition class for conditions relating to this library.

Package

cl-monitors

Source

wrapper.lisp (file)

Direct superclasses

condition (condition)

Direct subclasses

• initialization-failed-error (condition)
• detection-failed-error (condition)
• mode-switch-failed-error (condition)

5.1.5 Classes

Class: mode ()

Class representing a possible display mode of a monitor.

See MONITOR
See WIDTH
See HEIGHT
See REFRESH
See CURRENT-P

Package

cl-monitors

Source

wrapper.lisp (file)

Direct superclasses

foreign-object (class)

Direct methods

• (setf mode) (method)
• refresh (method)
• height (method)
• width (method)
• current-p (method)
• print-object (method)
• monitor (method)

Direct slots

Slot: monitor

Initargs

:monitor

Readers

monitor (generic function)

Direct Default Initargs

Initarg	Value
:monitor	(error "monitor required.")

Class: mode-struct ()

CL type for the C mode struct.

See MODE-MONITOR
See MODE-WIDTH
See MODE-HEIGHT
See MODE-REFRESH
See MODE-DATA

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Direct superclasses

• translatable-foreign-type (class)
• foreign-struct-type (class)

Class: monitor ()

Class representing a physical monitor on the system.

See MODES
See MODE
See NAME
See PRIMARY-P
See WIDTH
See HEIGHT

Package

cl-monitors

Source

wrapper.lisp (file)

Direct superclasses

foreign-object (class)

Direct methods

• height (method)
• width (method)
• primary-p (method)
• name (method)
• (setf mode) (method)
• initialize-instance (method)
• print-object (method)
• mode (method)
• modes (method)

Direct slots

Slot: modes

Readers

modes (generic function)

Slot: mode

Readers

mode (generic function)

Class: monitor-struct ()

CL type for the C monitor struct.

See MONITOR-NAME
See MONITOR-PRIMARY
See MONITOR-WIDTH
See MONITOR-HEIGHT
See MONITOR-MODE-COUNT
See MONITOR-CURRENT-MODE
See MONITOR-MODES
See MONITOR-DATA
See MONITORS-FREE-MONITOR

Package

cl-monitors-cffi

Source

low-level.lisp (file)

Direct superclasses

• translatable-foreign-type (class)
• foreign-struct-type (class)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *here*

Package

cl-monitors-cffi

Source

low-level.lisp (file)

5.2.2 Macros

Macro: define-foreign-reader (NAME INTERNAL-NAME) (CLASS)

Package

cl-monitors

Source

wrapper.lisp (file)

5.2.3 Generic functions

Generic Function: pointer OBJECT

Package

cl-monitors

Methods

Method: pointer (FOREIGN-OBJECT foreign-object)

automatically generated reader method

Source

wrapper.lisp (file)

5.2.4 Classes

Class: foreign-object ()

Package

cl-monitors

Source

wrapper.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• mode (class)
• monitor (class)

Direct methods

pointer (method)

Direct slots

Slot: pointer

Initargs

:pointer

Readers

pointer (generic function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types