display-non-focus-message Function

Summary

Display 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

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.

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*