SWI-Prolog -- class display

1.45 class display

Class display is xpce's handle on the host's graphical output: a physical monitor, the system theme, DPI, system clipboard and the collection of frames currently hosted on that monitor. The underlying driver is SDL3 across all platforms.

xpce creates a single instance at boot, bound to the primary monitor and reachable as @display. Additional display instances appear dynamically when a hotplugged monitor is attached (and disappear on removal). Most applications never reference any other display than @display.

See also: - display<-convert
- display<-dpi
- display<-primary
- class display_manager

1.45.1 Class variables

display.background: colour = white: Default background for newly created windows.
display.foreground: colour = black: Default foreground for newly created windows.
display.label_font: font = bold: Font used for the prompt of display->inform and display->confirm. Companion: display.value_font.
display.value_font: font = normal: Font used for the body of display->inform / display->confirm.
display.dpi: [size|int] =: @default Override for the resolution reported by SDL. @default lets SDL decide.
display.theme: [name] =: @default SWI-Prolog theme module to load for swipl-win / epilog. If @default, the choice is derived from display<-system_theme.
display.volume: 0..100 = 0: Default volume for display->bell.

1.45.2 Instance variables

display <-> name: name

Human-readable name reported by the OS for this monitor.

display <- number: int

Numeric identity assigned to the monitor; stable across the life of the process and used by the geometry syntax (e.g. "+0+0:1" picks monitor 1).

display <-> primary: bool

@on when this display is the OS-designated primary monitor. Exactly one display has this set at any time.

display <- area: area

Pixel rectangle occupied by this monitor in the global desktop coordinate space.

display <- work_area: area

Subrectangle of display<-area available for application windows (the rest is reserved by the desktop, e.g. for taskbars and docks).

display <- frames: chain

Chain of all frames currently hosted on this display. Maintained by frame->create and frame->unlink; frames that have not been created yet do not appear here.

See also: - frame->create
- class frame

display <- display_manager: display_manager

The global display manager (@display_manager).

See also: class display_manager

display <-> foreground: colour

Initial foreground colour for newly created windows. Changing this does not affect existing windows.

display <-> background: colour

Initial background colour for newly created windows. Changing this does not affect existing windows.

See also: window->background

display <- inspect_handlers: chain

Chain of handler objects used to support debugging tools. When an event occurs on a window and this chain is non-empty, the handlers in this chain are tried before the normal event-handling procedure.

xpce searches for the deepest nested graphical that overlaps the event-position. A possible event focus is ignored. If the event matches the type of the handler, the message of the handler is executed with the following argument binding:

@receiver The graphical

@arg1 Idem

@arg2 The event

If this message succeeds, the event is considered to be dealt with.

See also: - tool Inspector
- display->inspect_handler

1.45.3 Send methods

display ->initialise: name=name, area=area

Create a display for the monitor with the given OS-reported name and area. @display and any additional hotplugged displays are created automatically; applications normally do not call this.

display ->unlink:

Detach the display from @display_manager. Invoked by the display-manager when the monitor is removed.

display ->removed:

Mark the display as hotplug-removed. Existing frames keep running until they are destroyed; no new frames are accepted.

display ->poll_dimensions:

Re-query the OS for the monitor's display<-area, display<-work_area and display<-dpi. Called automatically on display events; can be invoked to refresh after an external change.

display ->bell: volume=[0..100]

Ring the bell on this display. Volume defaults to display.volume.

See also: - display.volume
- frame->bell
- graphical->bell

display ->busy_cursor: cursor=[cursor]*, block_input=[bool]

Define (temporary) cursor for all frames on the display by calling frame->busy_cursor on every entry in display<-frames. Used by popup->execute and click_gesture->terminate.

display ->confirm: for=[visual], title=[char_array], message=char_array, any ...

Format a string from the arguments and display a modal dialog asking the user to confirm. Returns success on confirm, failure on cancel.

See also: - pce->confirm
- string->format
- display->inform

display ->inform: for=[visual], title=[char_array], message=char_array, any ...

Display a modal information dialog and wait for the user to dismiss it. The first argument is a format string; the remaining arguments are substituted via string->format. See also pce->format and visual->report.

See also: - pce->inform
- string->format
- graphical->alert
- display->confirm

display ->report: kind={status,inform,progress,done,warning,error,fatal}, format=[char_array], argument=any ...

Catch-all for display->report messages on visual objects. inform and error invoke display->inform; error and warning also send graphical->alert to @reportee. Status reports are ignored.

display ->dispatch:

Invoke display_manager->dispatch to dispatch events for about 1/4 of a second.

See also: display_manager->dispatch

display ->event_queued:

Succeeds if there are events waiting in the OS queue for this display. Does not handle them.

display ->copy: char_array

Place the argument on both the primary selection and the system clipboard.

display ->selection: which=[name], value=char_array

Become owner of the selection (primary or clipboard) with the given textual value.

display ->screen_saver: bool

Activate (@on) or inhibit (@off) the OS screensaver while xpce is running.

display ->screen_keyboard: [{auto,on,off}]

Policy for showing the on-screen keyboard when a text-input widget gains focus. auto lets SDL decide based on whether a physical keyboard is attached.

display ->dpi: size|int

Override the display's reported resolution in dots per inch. Useful when the OS misreports DPI for high-density screens.

display ->inspect_handler: handler

Add a handler to display<-inspect_handlers (using chain->add).

See also: - topic Finding References
- display<-inspect_handlers

display ->has_visible_frames:

Succeeds if at least one frame on this display is currently visible.

1.45.4 Get methods

display <-contained_in: -> display_manager

Implements visual<-contained_in protocol.

display <-contains: -> chain

Implements visual<-contains protocol.

display <-convert: any -> display

Convert a graphical to the display it is shown on, or accept an already-existing display object.

display <-depth: -> bits_per_pixel=int

Bits used to represent a display pixel. Returns 32 (RGBA) on all current platforms; preserved for compatibility with code that branched on colour depth.

display <-size: -> size

Pixel size of the display: equivalent to display<-area.

display <-width: -> int

Pixel width of the display: equivalent to display<-area.

display <-height: -> int

Pixel height of the display: equivalent to display<-area.

display <-dpi: -> size

Resolution of the display in dots per inch. Either the value set via display->dpi, the override from the class variable, or the value SDL reports for the monitor.

display <-system_theme: -> {light,dark}

The OS system theme as reported by SDL_GetSystemTheme(). Some platforms cannot report this reliably.

display <-theme: -> name

SWI-Prolog theme to load for swipl-win (epilog). Derived from the class variable; if that is @default, derived from display<-system_theme. Setting it to a non-@default value causes use_module(library(theme/Theme)) to be loaded.

display <-paste: which=[{primary,clipboard}] -> string

Return the textual content of the indicated selection (defaults to clipboard). Pair with display->copy and display->selection.

See also: - display->copy
- display<-selection

display <-selection: which=[name], target=[name], type=[type] -> any

Query the value of a system selection. which defaults to primary; common alternatives are clipboard and secondary. target is the requested MIME-like type (default text; utf8_string for explicit UTF-8). type is the xpce type the returned value should be coerced to via type<-check.

See also: display<-paste

display <-has_screen_keyboard_support: -> bool

@on when SDL reports the platform has an on-screen keyboard.

display <-screen_keyboard_shown: -> bool

@on when the on-screen keyboard is currently visible.