display-non-focus-message Function

Summary

Displays a message in a non-focus window for a short period of time.

Package

capi

Signature

display-non-focus-message string &key timeout timeout-extension owner x alternative-x right y alternative-y bottom alternative-right alternative-bottom transparency background font widget-name pointing-to-x pointing-to-y pointing-to-width pointing-to-height position

Arguments

Description

The function display-non-focus-message displays a message in a non-focus window for a short period of time, to notify the user of something that does not actually require their attention.

string is the message. It should be either a string, or a list of strings, which are concatenated with newlines to give the actual text to display. #\Newline characters in string break lines as expected.

timeout, if supplied, should be a positive integer. It specifies the time in seconds before the window displaying the message disappears. The default value of timeout is *default-non-focus-message-timeout*.

timeout-extension is used when the user tries to copy the message text. The default value of timeout-extension is *default-non-focus-message-timeout-extension*. See "Copying from the message" below for discussion.

owner should be a visible CAPI pane. The positioning of the non-focus window is with respect to owner.

x, y, right, bottom, alternative-x, alternative-y, alternative-right, and alternative-bottom are used for positioning the window. x, alternative-right, alternative-x and right are the horizontal keywords, and one of them determines the horizontal position as described below. y, alternative-bottom, alternative-y and bottom are the vertical keywords, and one of them determines the vertical position. The values :center and :centre are synonyms here.

x and y specify the positioning of the left and top sides of the window, except for :center/:centre. An integer means the offset in pixels from the left or top of owner. :left, :right, :top and :bottom mean the left/right/top/bottom of owner. :center means the center of owner, and in this case it specifies the location of the center of the window in the x or y dimension. The default value of both x and y is :center.

right and bottom override x and y respectively. They specify the positioning of the right or bottom of the window, except for :center/:centre, where they are interpreted in the same way as x and y.

alternative-x, alternative-y, alternative-right, and alternative-bottom are used if positioning the window using x or right and y or bottom would place it outside of the screen, and are interpreted the same way as the non-alternative keywords. The decision to use the alternative variables is made independently in the horizontal and vertical directions. alternative-right and alternative-bottom can both take the special value t, meaning the screen width and height.

The Wayland positioning arguments pointing-to-x, pointing-to-y, pointing-to-width, pointing-to-height and position are currently used only when displaying with GTK+ on Wayland, and otherwise are ignored. You can check if the dislay is on Wayland using screen-display-type.

Wayland does not allow applications to specify the position of a window, so LispWorks cannot properly position the non-focus window. Instead, when displaying with GTK+ on Wayland, LispWorks uses a "popover" (an instance of GtkPopover), which allows some control. A "pointing-to" rectangle can be specified, plus the position of the "popover" relative to the rectangle. LispWorks uses heuristics to try to position the "popover" in the correct place using these. In case the heuristics are not good enough, you can use the Wayland positioning arguments to specify it explicitly.

pointing-to-x, pointing-to-y, pointing-to-width and pointing-to-height specify the dimensions of the "pointing-to" rectangle. If any of these is nil (the default), then LispWorks uses heuristics to choose a value to use. The rectangle is relative to owner, and specifies a rectangle that the "popover" will point to but will not cover.

If position is nil (the default), the position of the "popover" with respect to the "pointing-to" rectangle on Wayland is decided by heuristics, either by LispWorks itself or by GTK+. Otherwise, the "popover" is displayed at the position specfied by position, which should be one of :top, :left, :bottom or :right, which positions the "popover" above, to the left of, below or to the right of the "pointing-to" rectangle respectively.

transparency specifies the transparency of the window. See interface for details.

background specifies the background color of the window.

font specifies the font to use. If it is a positive integer it specifies the font size, that is equivalent to:

(gp:make-font-description :size font)

widget-name specifies the widget-name of the interface that displays the window. See element for details.

Copying from the message

The user can select part of the message with the mouse, and then copy it using the context menu (raised by right-click). Whenever the user changes the selection or cursor position, a timout specified by timeout is re-scheduled with timeout-extension seconds, so the window does not disappear while the user tries to copy.

The context menu also has a Close item, so the user can explicitly close the window once she has finished.

Notes

Because display-non-focus-message raises a window that does not take the focus, it does not interfere with what the user is already doing (except when the user clicks on the window). It is therefore useful to notify the user about events that do not actually require the user to stop what they are doing and do something, for example when a saving operation is complete.

See also

display-message
*default-non-focus-message-timeout*
*default-non-focus-message-timeout-extension*