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 container.

Description

The function convert-to-screen finds the appropriate screen or 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 capi:container of the 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/7-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, AIX and x86/x64 Solaris platforms, and in the Mac OS X/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.

Example

(capi:convert-to-screen)

See also

document-frame
screen
Host Window System-specific issues