Class

Summary

The class text-input-pane is a pane for entering a single line of text.

Superclasses

titled-object
simple-pane

Subclasses

multi-line-text-input-pane
password-pane
text-input-choice

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

A boolean controlling whether the pane is enabled.

:completion-function

A function called to complete the text.

:callback-type

The type of arguments to callback .

:callback

A function 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 MacOS.

Accessors

text-input-pane-text
text-input-pane-max-characters
text-input-pane-completion-function
text-input-pane-callback
text-input-pane-confirm-change-function
text-input-pane-change-callback
text-input-pane-enabled

Readers

text-input-pane-caret-position

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). The pane is enabled or disabled according to the value of the enabled slot.

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.

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

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.

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

Compatibility Note

The confirm-change-function was called before-change-callback in LispWorks 3.1. Both the old initarg before-change-callback and the old accessor text-input-pane-before-change-callback are still supported, but may not be in future releases.

Examples

(capi:contain (make-instance 'capi:text-input-pane

                             :text "Hello world"))

(setq text-input-pane (capi:contain

                       (make-instance 

                        'capi:text-input-pane

                        :enabled nil)

                       :process nil))

(setf (capi:text-input-pane-enabled text-input-pane) t)

(setf (capi:text-input-pane-enabled text-input-pane)

      nil)

(setf (capi:text-input-pane-text text-input-pane)

      "New text")

(capi:contain (make-instance 'capi:text-input-pane

                             :max-characters 10))

(capi:contain (make-instance

               'capi:text-input-pane

               :text "Hello world"

               :callback #'(lambda (text interface)

                             (capi:display-message

                              "Interface ~S's text: ~S"

                              interface text))))

There is a further example in the file examples/capi/elements/text-input-pane.lisp

See also

display-pane
editor-pane
multi-line-text-input-pane
text-input-choice
text-input-pane-complete-text
text-input-range
title-pane