Class display is xpce's handle on the host's graphical
output: a physical monitor, the system theme, system clipboard and the
collection of frames currently hosted on that monitor. The underlying
driver is SDL3 across all platforms.
xpce creates an instance for each monitor when the window system is
initialised. Additional display instances appear
dynamically when a hotplugged monitor is attached (and disappear on
removal, except for the last one; see display->removed).
Most applications use @display,
the function that evaluates to the display that received the last event
or else the primary display. See display_manager<-current.
->inform
and
display->confirm.
Companion: display.value_font.->inform
/
display->confirm..g., dark.
If @default,
the theme follows
display<-system_theme,
also if this changes while xpce is running. Set this in the Defaults
file to select a theme permanently. The Settings/Theme menu of the IDE
sets it for the running session. See library(pce_theme).library(find_file)
(@finder, used by, e.g.,
file_item->browse) uses the file dialog of
the desktop via
frame<-open_file, frame<-save_file
and
frame<-open_directory.
If @off, or if
no frame is shown, it uses the dialog of xpce (class find_file_dialog).->bell.->bell
in Hz..2 Length of the tone of display->bell
in seconds.->bell
plays instead of the tone, e.g., a WAV or Ogg
file. See sound->load
for the formats. If the file cannot be loaded, the bell plays the tone.
.g.
"+0+0:1" picks monitor 1).<-area
available for application windows (the rest is reserved by the desktop, e.g.
for taskbars and docks).->create
and frame->unlink;
frames that have not been created yet do not appear here.
display_manager <-inspect_handlers. 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.
<-primary.
The display is freed when it has no frames left. If it was the last
display it is kept as a parking place: frames stay on it and new frames
open on it, so @display
does not fail. When a monitor is attached again, the frames move to it
and the parked display is freed.<-area
and display<-work_area.
Called automatically on display events; can be invoked to refresh after
an external change.<-bell_sound.
Volume defaults to display.volume.
->busy_cursor
on every entry in display<-frames.
Used by
popup->execute
and click_gesture->terminate.
Use
display_manager->busy_cursor
for all frames of the application.->format.
See also
pce->format
and visual->report.
->report
messages on visual
objects. inform and error invoke display->inform; error
and warning also send
graphical->alert
to @reportee.
Status reports are ignored.->dispatch to
dispatch events for about 1/4 of a second.
|image|graphical->selection.|image|graphicalprimary or clipboard)
with the given value. An image or graphical can only be placed on the
clipboard. An image is offered as PNG (image/png); a
graphical is offered as SVG (image/svg+xml, see graphical->svg)
and PNG, so other applications can paste the format they prefer.auto lets SDL decide based on whether a physical
keyboard is attached.<-inspect_handlers
(using chain->add).
As this chain is shared, the handler applies to all displays.
keep_alive
is @on, only
frames whose
frame<-keep_alive
is @on count.
value 1 or 0) or axis (-1..1) of it.
<-contained_in
protocol.<-contains
protocol.<-area.<-area.<-area.SDL_GetSystemTheme(). On
Windows, a contrast theme with a dark window background also counts as dark.
Fails if the platform cannot tell..theme
or, if that is @default, display<-system_theme.
library(pce_theme) applies this theme when xpce starts and,
if the class variable
is @default,
when the desktop switches between light and dark.clipboard).
Pair with display->copy
and display->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). For the clipboard, target
may also be image, returning an image from PNG, JPEG or
another image format on the clipboard, or svg, returning
the SVG document as a string. type is the xpce type the
returned value should be coerced to via type<-check.
It defaults to image for the target image and string
otherwise.
clipboard), e.g., 'text/plain;charset=utf-8'
or
'image/png'. This allows a paste command to decide what to
paste.When a device is added or removed, e.g., a
gamepad is plugged in, the window with the keyboard focus of each frame
receives a device_added or device_removed event, whose event<-device
is the device.
.g.,
if the system has no battery.en_US or nl.->bell
plays: the file of display.bell_sound
or else a tone (see sound->tone)
of display.bell_pitch
Hz that lasts
display.bell_duration
seconds.->load
can load, e.g., wav, mp3, ogg
and flac. This is only wav if xpce is built
without SDL3_sound.->save
can write, e.g., png,
jpeg and gif. Whether webp and avif
are included depends on how SDL_image was built..g., h264, hevc, av1
and vp9. Empty if xpce is built without video support.ffmpeg, media_foundation
or
avfoundation, or @nil
if xpce is built without video support.->sdl_test_gamepad.