convert-to-screen

convert-to-screen Function

Summary

Finds the appropriate screen or container for a CAPI object.

Package

capi

Signature

convert-to-screen &optional object => result

Arguments

object⇩

A CAPI object, a plist, or keyword or nil.

Values

result⇩

A screen or a document-container.

Description

The function convert-to-screen finds the appropriate screen or document container for the CAPI object object.

If object is nil, result is the default screen. object defaults to nil.

If object is a pane inside a MDI interface, then result is the document-container in the capi:container slot of the MDI interface, rather than the real screen, because this is more useful in most cases. To obtain the real screen, call convert-to-screen on the top level interface. See document-frame for a description of MDI interfaces.

object can be a keyword representing the CAPI library. This is equivalent to using the :library key in the plist case below. object can also be the special keyword :if-any, which finds a screen if there is any active screen, otherwise it returns nil.

object can be a plist. The keys below are supported on GTK+ and Motif. Other libraries ignore them.

`:display`	The value is an X Window System display string describing the X display and screen to use. The default value is derived from the `DISPLAY` environment variable or (on Motif) the `-display` command-line option, or (on GTK+) the `--display` command-line option. If neither is supplied, the default is to use the default screen on the local host.
`:host`	The name of the host to use for the X Window System display. This key is valid only if no `:display` key/value is supplied. The default value is the local host.
`:server-number`	The number of the display server to use for the X Window System display. This key is valid only if no `:display` key/value is supplied. The default value is 0.
`:screen-number`	The number of the screen to use for the X Window System display. This key is valid only if no `:display` key/value is supplied. The default value is the default screen of the display.
`:application-class`	The value is a string naming the application class used for X Window System resources. The default value is "Lispworks". When running a delivered LispWorks image, you should specify the `:application-class` key if you want to provide application-specific resources. On GTK+ the value is used for constructing the default `widget-name` for top-level interfaces. The application-class is prepended to the interface name followed by a ".", so if `application-class` is `"my-application"`, a top-level-interface of class `my-interface` will have a default `widget-name` `"my-application.my-interface"`. See element for the description of `widget-name`. Example GTK+ resource files are in `lib/8-1-0-0/examples/gtk/`.
`:fallback-resources`
	On GTK+ the fallback resources are global, so they cannot be used to define different resources for different screens. Each call to `convert-to-screen` where `fallback-resources` is passed overrides the previous call. The value of `fallback-resources` is either a single string or a list of strings. In either case each string must be a complete specification according to the standard resource specification of GTK+ resource files (gtk_rc_parse_string should be able to parse it). On Motif the value is a list of strings representing the set of application context fallback resources to use (see `XtAppSetFallbackResources`). Each string corresponds to a single line of an X resource file.
`:library`	The value specifies the CAPI library. This is useful on Linux, FreeBSD and x86/x64 Solaris platforms, and in the macOS/GTK+ image, to choose between `:gtk` and `:motif` if the deprecated "capi-motif" module is loaded.

This keys is supported on Motif only. Other libraries ignore it.

:command-line-args

The value is a list of strings representing the set of command-line arguments to pass to XtOpenDisplay. Each string corresponds to a single argument. The default value is derived from the command line used to start Lisp.

The resources are used only when no other system resource files can be found. When running a non-delivered LispWorks image, the default value of the :fallback-resources key is read from the file whose name is the value of the :application-class key in the app-defaults directory of the current LispWorks library. When running a delivered LispWorks image, you should specify the :fallback-resources key if your application needs fallback resources.

Examples

(capi:convert-to-screen)