text-input-pane

Initargs

:text

The text in the pane.

:caret-position

The position of the caret in the text (from 0).

:max-characters

The maximum number of characters allowed.

:enabled

Controls the enabled state of the pane.

:completion-function

A function called to complete the text.

:callback-type

The type of arguments to callback .

:callback

A function usually called when the user presses Return .

:change-callback-type

The type of arguments to callback .

:change-callback

A function called when a change is made.

:confirm-change-function

A function called to validate a change. Note: Implemented for Motif/Lesstif only, not MS Windows or Mac OS X.

:navigation-callback

A function called when certain keyboard gestures occur in the pane.

:editing-callback

A function called when editing starts or stops.

:buttons

A plist specifying buttons to add, or t or nil .

Description

The class text-input-pane provides a great deal of flexibility in its handling of the text being entered. It starts with the initial text and caret-position specified by the arguments text and caret-position respectively. It limits the number of characters entered with the max-characters argument (which defaults to nil , meaning there is no maximum).

If enabled is nil , the pane is disabled. If enabled is :read-only , then the pane shows the text and allows it to be selected without it being editable. In this case the visual appearance varies between window systems, but often the text can be copied and the caret position altered. If enabled is any other true value, then the pane is fully enabled. The default value of enabled is t .

A completion-function can be specified which will get called when the completion gesture is made by the user (or pressing the Tab key) or when text-input-pane-complete-text is called. The completion-function is called with the pane and the text to complete and should return either nil , the completed text or a list of candidate completions. In the latter case, the CAPI will prompt the user for the completion they wish, and this will become the new text.

callback , if non-nil , is called when the user presses Return , unless navigation-callback is non-nil , in which case navigation-callback is called instead.

When the text or caret-position is changed, the callback change-callback is called with the text , the pane itself, the interface and the caret-position . The arguments that are passed to the change-callback can be altered by specifying the change-callback-type (see the callbacks class for details of possible values).

Note: the change-callback is potentially called more than once for each user gesture.

With the Motif/Lesstif implementation it is possible to check changes that the user makes to the text-input-pane by providing a confirm-change-function which gets passed the new text, the pane itself, its interface and the new caret position, and which should return non-nil if it is OK to make the change. If nil is returned, then the pane will be unaltered and a beep will be signalled to indicate that the new values were invalid.

navigation-callback , if non-nil , is a function that will be called when certain navigation gestures are used in the text-input-pane . The function is called with two arguments, the pane itself, and one of the following keywords:

:tab-forward

Tab was pressed.

:tab-backward

Tab Backwards (usually Shift+Tab ) was pressed.

:return

Return was pressed.

:shift-return

Shift+Return was pressed.

:enter

Enter was pressed.

:shift-enter

Shift+Enter was pressed.

Note: Enter is the key usually found on the numeric keypad.

When navigation-callback is non-nil , it is called instead of callback when Return is pressed. callback is still called via an OK button if there is one (see buttons below).

navigation-callback is implemented only on Windows and Cocoa.

editing-callback , if non-nil , is a function that will be called with the keyword :start when the user starts editing and the keyword :end when the user stops editing. In general, this occurs when the focus changes, but on Cocoa :start is passed when the first change is made to the text.

buttons specifies toolbar buttons which appear next to the pane and facilitate user actions on it. It also specifies the position of the buttons relative to the pane. This feature appears in the Common LispWorks IDE, for example the Class box of the Class Browser.

The allowed keys and values of the plist buttons are:

:ok

A boolean or a plist, default value t . If true, a button which calls callback appears. If the value is a plist then this plist supplies details for the button, as described below.

:cancel

A boolean or a plist, default value nil . If true, a button which calls cancel-function appears. A plist value is interpreted as for :ok .

:completion

A boolean or a plist. If true, a button which calls completion-function appears. The default value is t if completion-function is non-nil , and nil otherwise. A plist value is interpreted as for :ok .

:browse-file

A keyword or a plist. If true, a button which invokes prompt-for-file appears. If the value is :save or :open then it is passed as the operation argument to prompt-for-file, replacing the text in the pane if successful. If the value is a plist, then it supplies details for the button, as described below, and can also contain the keywords :message to specify a message for the file prompter; :pathname to specify the default pathname of the file prompter (defaults to the text in the text-input-pane ) or any of the keywords :ok-check , :filter , :filters , :if-exists , :if-does-not-exist , :operation , :owner , :pane-args or :popup-args which are passed directly to prompt-for-file.

:cancel-function

A function that expects the pane as its single argument. The default is a function which sets text to the empty string.

:orientation

The value is either :horizontal or :vertical . orientation controls the orientation of the toolbar. This is useful for multi-line-text-input-pane. The default value is :horizontal .

:adjust

The value is :top , :center , :centre or :bottom . adjust controls how the buttons are adjusted vertically relative to the text input pane. This is useful for multi-line-text-input-pane. The default value is :center .

:position

The value is :top , :bottom , :left or :right . position determines whether the buttons appear above, below, left or right of the text input pane. If :position is not supplied, then the buttons appear to the right of the pane.

The value nil for buttons means there are no buttons - this is the default. When buttons is true the buttons appear or not according to their specified values or their default values.

Each of the :ok , :cancel and :completion buttons keys can have a plist value, in which the following keys and values are allowed:

:enabled

A value that controls whether the button is enabled. (See the reader text-input-pane-buttons-enabled ).

:image

The image to use for the button. This should be either a pathname or string naming an image file to load, a symbol giving the id of an image registered with register-image-translation, an image object as returned by load-image or an external-image.. The default image is one of the symbols ok-button , cancel-button or complete-button , which are preregistered image identifers corresponding to each button.

:help-key

The help-key used to find a tooltip for the button.

:accelerator

The accelerator used for the button. There is no default accelerator and this key is only used for the :cancel button.

The text-input-pane-buttons-enabled reader returns a list containing the keywords :ok , :cancel and :completion , one for each corresponding button (as specified by buttons ) that is currently enabled.

The (setf text-input-pane-buttons-enabled) writer takes a list of keywords as described for the reader and sets the enabled state of the buttons, enabling each button if it appears in the list and disabling it otherwise. The value t can also be passed: this enables all the buttons.

For more than one line of input, use multi-line-text-input-pane.

text-input-pane

Class

Summary

Package

Superclasses

Subclasses

Initargs

Accessors

Readers

Description

Compatibility Note

Examples

See also