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 y alternative-right alternative-bottom alternative-x alternative-y bottom right transparency background font widget-name

Arguments

string

A string or a list of strings.

timeout

A positive integer.

timeout-extension

A positive integer.

owner

A visible CAPI pane

x , alternative-x , right

An integer, or one of the keywords :left, :right, :center and :centre.

alternative-right

An integer, or one of the keywords :left, :right, :center and :centre, or t.

y , alternative-y , bottom

An integer, or one of the keywords :top, :bottom, :center and :centre.

alternative-bottom

An integer, or one of the keywords :top, :bottom, :center and :centre, or t.

transparency

A real number in the inclusive range [0,1].

background

A color in the Graphics Ports color system.

font

A font or a font-description, or a positive integer.

widget-name

A string designator.

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 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 the 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, the 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*